Simulation software for safe, sustainable and future deltas

Delft3D FM Suite

T
AF
DR

D-Flow Flexible Mesh

User Manual
 T
AF
D-Flow Flexible Mesh

Computational Cores and User Interface

DR

User Manual

Released for:
Delft3D FM Suite 2D3D 2025

Version: 2025
Revision: 80183

11 April 2025
 D-Flow Flexible Mesh, User Manual

T
AF
DR

Published and printed by:

Deltares telephone: +31 88 335 82 73
Boussinesqweg 1 e-mail: Information
2629 HV Delft www: Deltares
P.O. 177
2600 MH Delft
The Netherlands

For sales contact: For support contact:

telephone: +31 88 335 81 88 telephone: +31 88 335 81 00
e-mail: Sales e-mail: Support
www: Sales & Support www: Sales & Support

Copyright © 2025 Deltares

All rights reserved. No part of this document may be reproduced in any form by print, photo
print, photo copy, microfilm or any other means, without written permission from the publisher:
Deltares.
 Contents

T
List of Tables xv

List of Figures xvii

1 A guide to this manual 1

AF
1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . .
1
1
2

2 Introduction to D-Flow Flexible Mesh 4

2.1 Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2 Modelling capabilities and advantages . . . . . . . . . . . . . . . . . . . . 5
2.3 Current limitations for Delft3D Flexible Mesh Suite . . . . . . . . . . . . . . 5
2.3.1 General limitations . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3.2 Limitations for D-Flow FM 2D3D . . . . . . . . . . . . . . . . . . . 5
2.4 Coupling to other modules . . . . . . . . . . . . . . . . . . . . . . . . . . 6
DR

2.5 Installation of D-Flow Flexible Mesh . . . . . . . . . . . . . . . . . . . . . . 6

2.6 Important differences compared to Delft3D-FLOW . . . . . . . . . . . . . . 7

3 Conceptual description of hydrodynamic equations 8

3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.2 Physical processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.3 Hydrodynamic modelling . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3.1 Model equations in 2D . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3.1.1 Momentum equations in horizontal direction (2D) . . . . . . 10
3.3.1.2 Continuity equation (2D) . . . . . . . . . . . . . . . . . . 10
3.3.2 Model equations in 3D . . . . . . . . . . . . . . . . . . . . . . . . 10
3.3.2.1 Momentum equations in horizontal direction (3D) . . . . . . 10
3.3.2.2 Vertical velocities (3D) . . . . . . . . . . . . . . . . . . . 11
3.3.3 The hydrostatic pressure assumption . . . . . . . . . . . . . . . . . 11
3.3.4 The Coriolis force . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.3.5 Diffusion of momentum . . . . . . . . . . . . . . . . . . . . . . . . 12
3.3.6 Bed friction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.3.7 Roughness definition input . . . . . . . . . . . . . . . . . . . . . . 15
3.4 Equations of state for the density . . . . . . . . . . . . . . . . . . . . . . . 16
3.5 Shear-stresses at closed boundaries . . . . . . . . . . . . . . . . . . . . . 17
3.6 Secondary flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.6.1 Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.6.2 Momentum equations in horizontal direction . . . . . . . . . . . . . 19
3.6.3 Effect of secondary flow on depth-averaged momentum equations . . 19
3.6.4 The depth averaged transport equation for the spiral motion intensity . 20
3.7 Tide generating forces . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.8 Wave forcing in D-Flow FM . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.8.1 Forcing by radiation stress gradients . . . . . . . . . . . . . . . . . 24

iii
 CONTENTS

3.8.2 Stokes drift and mass flux . . . . . . . . . . . . . . . . . . . . . . 25

3.8.3 Enhancement of the bed shear-stress by waves . . . . . . . . . . . 26
3.9 Assumptions underlying D-Flow FM . . . . . . . . . . . . . . . . . . . . . . 30

4 Conceptual description of transport equation 33

4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.2 Transport processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.2.1 Advection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.2.2 Diffusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.2.2.1 Time integration of horizontal diffusion . . . . . . . . . . . 35

T
4.2.3 Sources and sinks . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.2.4 Forester filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.3 Boundary and initial conditions for transport equation . . . . . . . . . . . . . 37
4.3.1 Open boundary conditions . . . . . . . . . . . . . . . . . . . . . . 37
4.3.2 Closed boundary conditions . . . . . . . . . . . . . . . . . . . . . 38
AF 4.3.3 Vertical boundary conditions . . . . . . . . . .
4.3.4 Thatcher-Harleman boundary conditions . . . .
4.3.5 Initial conditions . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
38
38
39
4.4 Introduction to sediment transport . . . . . . . . . . . . . . . . . . . . . . . 40

5 Conceptual description of heat flux models 41

5.1 Heat balance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5.2 Solar radiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
5.3 Atmospheric radiation (long wave radiation) . . . . . . . . . . . . . . . . . . 47
5.4 Back radiation (long wave radiation) . . . . . . . . . . . . . . . . . . . . . . 48
5.5 Effective back radiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
DR

5.6 Evaporative heat flux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

5.7 Convective heat flux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

6 Getting started with Graphical User Interface 52

6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.2 Overview of D-Flow FM GUI . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.2.1 Project window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.2.2 The central window . . . . . . . . . . . . . . . . . . . . . . . . . . 54
6.2.3 Settings window . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
6.2.4 Map window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
6.2.5 Messages window . . . . . . . . . . . . . . . . . . . . . . . . . . 55
6.2.6 Time Navigator window . . . . . . . . . . . . . . . . . . . . . . . 55
6.3 Dockable views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.3.1 Docking tabs separately . . . . . . . . . . . . . . . . . . . . . . . 56
6.3.2 Multiple tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.4 Ribbons and toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
6.4.1 Ribbons (shortcut keys) . . . . . . . . . . . . . . . . . . . . . . . . 57
6.4.2 File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
6.4.3 Home . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.4.4 View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.4.5 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.4.6 Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.4.7 Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
6.4.8 Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
6.4.9 Quick access toolbar . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.5 Important differences compared to Delft3D-FLOW GUI . . . . . . . . . . . . 62
6.5.1 Project vs model . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.5.2 Load/save vs import/export . . . . . . . . . . . . . . . . . . . . . . 63

Deltares iv
 CONTENTS

6.5.3 Working from the map . . . . . . . . . . . . . . . . . . . . . . . . 63

6.5.4 Coordinate conversion . . . . . . . . . . . . . . . . . . . . . . . . 63
6.5.5 Model area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.5.6 Integrated models (model couplings) . . . . . . . . . . . . . . . . . 64
6.5.7 Ribbons (shortcut keys) . . . . . . . . . . . . . . . . . . . . . . . . 65
6.5.8 Context menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.5.9 Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

7 Set-up of a D-Flow FM model 66

7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

T
7.2 mdu-file and attribute files . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
7.3 Filenames and conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 67
7.4 How to set-up a D-Flow FM model . . . . . . . . . . . . . . . . . . . . . . 67
7.4.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
7.4.1.1 Model coordinate system . . . . . . . . . . . . . . . . . . 68
AF 7.4.1.2 Angle of latitude . . . . . . . . . . . . . . . . . . . . . . 69
7.4.2 Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
7.4.2.1 Grid-snapped features . . . . . . . . . . . . . . . . . . . 70
7.4.2.2 Observation points . . . . . . . . . . . . . . . . . . . . . 72
7.4.2.3 Observation cross-sections . . . . . . . . . . . . . . . . . 73
7.4.2.4 Thin dams . . . . . . . . . . . . . . . . . . . . . . . . . 74
7.4.2.5 Fixed weirs . . . . . . . . . . . . . . . . . . . . . . . . . 75
7.4.2.6 Land boundaries . . . . . . . . . . . . . . . . . . . . . . 77
7.4.2.7 Dry points and Dry areas . . . . . . . . . . . . . . . . . . 78
7.4.2.8 Pumps . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
7.4.2.9 Weirs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
DR

7.4.2.10 Gates . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
7.4.2.11 Bridge Pillars . . . . . . . . . . . . . . . . . . . . . . . . 83
7.4.3 Computational grid . . . . . . . . . . . . . . . . . . . . . . . . . . 84
7.4.4 Bed level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
7.4.5 Time frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
7.4.6 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
7.4.7 Initial conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
7.4.8 Boundary conditions . . . . . . . . . . . . . . . . . . . . . . . . . 89
7.4.8.1 Specification of boundary locations (support points) . . . . 89
7.4.8.2 Boundary data editor (forcing) . . . . . . . . . . . . . . . 91
7.4.8.3 Import/export boundary conditions from the Project window 104
7.4.8.4 Overview of boundary conditions in attribute table (non-editable)106
7.4.9 Physical parameters . . . . . . . . . . . . . . . . . . . . . . . . . 107
7.4.9.1 Constants . . . . . . . . . . . . . . . . . . . . . . . . . 107
7.4.9.2 Roughness . . . . . . . . . . . . . . . . . . . . . . . . . 107
7.4.9.3 Viscosity . . . . . . . . . . . . . . . . . . . . . . . . . . 109
7.4.9.4 Wind . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
7.4.9.5 Heat Flux model . . . . . . . . . . . . . . . . . . . . . . 110
7.4.9.6 Tidal forces . . . . . . . . . . . . . . . . . . . . . . . . . 110
7.4.10 Sources and sinks . . . . . . . . . . . . . . . . . . . . . . . . . . 110
7.4.11 Intakes, outfalls and coupled intake-outfalls . . . . . . . . . . . . . . 112
7.4.12 Lateral discharges . . . . . . . . . . . . . . . . . . . . . . . . . . 114
7.4.12.1 Grid snapping and distribution of discharge . . . . . . . . . 114
7.4.12.2 Forcing information for lateral discharges . . . . . . . . . . 115
7.4.12.3 Output for lateral discharges . . . . . . . . . . . . . . . . 115
7.4.13 Numerical parameters . . . . . . . . . . . . . . . . . . . . . . . . 115
7.4.14 Output parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 115
7.4.15 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Deltares v
 CONTENTS

7.4.16 3D Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

7.5 Save project, MDU file and attribute files . . . . . . . . . . . . . . . . . . . 121

8 Running a model 123

8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
8.2 Running a scenario using the User Interface . . . . . . . . . . . . . . . . . 123
8.3 Running a scenario using a batch script . . . . . . . . . . . . . . . . . . . . 124
8.3.1 Commandline executables . . . . . . . . . . . . . . . . . . . . . . 125
8.3.2 Running D-Flow FM . . . . . . . . . . . . . . . . . . . . . . . . . 125
8.4 Parallel computing using MPI . . . . . . . . . . . . . . . . . . . . . . . . . 126

T
8.4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
8.4.2 Partitioning a model . . . . . . . . . . . . . . . . . . . . . . . . . 127
8.4.2.1 More options for the partitioning . . . . . . . . . . . . . . 128
8.4.2.2 Partitioning the mdu-file . . . . . . . . . . . . . . . . . . 131
8.4.2.3 Remaining model input . . . . . . . . . . . . . . . . . . . 131
AF 8.4.3 Running a parallel job . . . . . . . . . . . . . . . . . . . . . . . .
8.4.3.1 A parallel simulation via DIMR . . . . . . . . . . . . . .
8.4.3.2 A parallel simulation on Linux via D-Flow FM . . . . . . .
.
.
.
131
131
132
8.4.4 Visualizing the results of a parallel run . . . . . . . . . . . . . . . . 132
8.4.4.1 Plotting all partitioned map files with Delft3D-QUICKPLOT . 133
8.4.4.2 Merging multiple map files into one . . . . . . . . . . . . . 133
8.5 Run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
8.5.1 Multi-core performance improvements by OpenMP . . . . . . . . . . 136
8.6 Files and file sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
8.6.1 History file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
8.6.2 Map file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
DR

8.6.3 Restart file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

8.7 D-Flow FM command-line argument . . . . . . . . . . . . . . . . . . . . . 138
8.8 Restart a simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
8.9 Frequently asked questions . . . . . . . . . . . . . . . . . . . . . . . . . . 140

9 Visualize results 142

9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
9.2 Visualization with the User Interface . . . . . . . . . . . . . . . . . . . . . . 142
9.3 Visualization with Delft3D-QUICKPLOT . . . . . . . . . . . . . . . . . . . . 143
9.4 Visualization with Matlab . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
9.5 Visualization with Python . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

10 3D modelling in D-Flow FM 145

10.1 Introduction to vertical layering approaches . . . . . . . . . . . . . . . . . . 145
10.2 σ -layer modelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
10.3 Z-layer modelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
10.4 Z-σ -layer modelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
10.5 Boundary conditions in 3D . . . . . . . . . . . . . . . . . . . . . . . . . . 149
10.6 Turbulence modelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
10.6.1 k-epsilon turbulence model . . . . . . . . . . . . . . . . . . . . . . 152
10.6.2 k-tau turbulence model . . . . . . . . . . . . . . . . . . . . . . . . 155
10.7 Fixed weirs for 3D modelling . . . . . . . . . . . . . . . . . . . . . . . . . 155
10.8 3D modelling guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
10.8.1 Non optimal default value in case of 3D modelling . . . . . . . . . . . 156
10.8.2 Number of layers . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
10.8.3 Anti creep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
10.8.4 Spurious oscillations in vertical velocity . . . . . . . . . . . . . . . . 157

11 Boundary conditions in D-Flow FM 159

Deltares vi
 CONTENTS

11.1 Hydrodynamics boundary conditions . . . . . . . . . . . . . . . . . . . . . 159

11.1.1 Open boundary conditions . . . . . . . . . . . . . . . . . . . . . . 159
11.1.1.1 Forcing information . . . . . . . . . . . . . . . . . . . . . 159
11.1.1.2 External forcings file . . . . . . . . . . . . . . . . . . . . 165
11.1.1.3 External forcings in model definition file . . . . . . . . . . . 165
11.1.1.4 Example . . . . . . . . . . . . . . . . . . . . . . . . . . 165
11.1.1.5 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . 167
11.1.2 Vertical boundary conditions . . . . . . . . . . . . . . . . . . . . . 170

12 Hydraulic structures 172

T
12.1 Fixed weirs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
12.2 Dam break . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
12.2.1 Grid snapping of a dam break . . . . . . . . . . . . . . . . . . . . 174
12.2.2 Computation of breach growth . . . . . . . . . . . . . . . . . . . . 174
12.2.2.1 The Verheij–Van der Knaap (2002) formula . . . . . . . . . 175
AF 12.2.2.2 The Van der Knaap (2000) formula . . . . . . . . .
12.2.2.3 Breach crest level and width time series . . . . . .
12.2.2.4 Method when breach grows wider than one flow link
.
.
.
.
.
.
.
.
.
. 177
. 178
. 179
12.3 General structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
12.3.1 Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
12.3.2 Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
12.3.3 Computation of the downstream water level . . . . . . . . . . . . . . 185
12.3.4 Turning off the computation of the energy levels . . . . . . . . . . . . 187
12.3.5 Discharge equations . . . . . . . . . . . . . . . . . . . . . . . . . 188
12.4 Weir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
12.5 Gates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
DR

12.6 Orifice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

12.7 Culvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
12.8 Long Culvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
12.8.1 Long culvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
12.9 Bridges in 1D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
12.10 Universal weir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
12.11 Pump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
12.11.1 Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
12.11.2 Orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
12.11.3 Staged pump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
12.11.4 Non-staged pump . . . . . . . . . . . . . . . . . . . . . . . . . . 203
12.11.5 Capacity reduction table . . . . . . . . . . . . . . . . . . . . . . . 204
12.11.6 Distribution and relaxation of pump discharge . . . . . . . . . . . . . 204
12.12 Compound structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
12.13 Thin dams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
12.14 Floating structures (via ice modelling) . . . . . . . . . . . . . . . . . . . . . 205

13 Bedforms and vegetation 206

13.1 Bedform heights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
13.2 Trachytopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
13.2.1 Trachytope classes . . . . . . . . . . . . . . . . . . . . . . . . . . 206
13.2.2 Averaging and accumulation of trachytopes . . . . . . . . . . . . . . 213
13.3 Dynamic vegetation model . . . . . . . . . . . . . . . . . . . . . . . . . . 214
13.3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
13.3.2 Philosophies of dynamic vegetation model . . . . . . . . . . . . . . 215
13.3.3 Conceptual description . . . . . . . . . . . . . . . . . . . . . . . . 215
13.4 (Rigid) three-dimensional vegetation model . . . . . . . . . . . . . . . . . . 216

Deltares vii
 CONTENTS

14 Calibration factor for bed roughness 217

15 Wind 218
15.1 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
15.1.1 Nautical convention . . . . . . . . . . . . . . . . . . . . . . . . . . 219
15.1.2 Drag coefficient . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
15.2 File formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
15.2.1 Defined on the computational grid . . . . . . . . . . . . . . . . . . 224
15.2.1.1 Specification of uniform wind through velocity components . 224
15.2.1.2 Specification of uniform wind through magnitude and direction226

T
15.2.2 Defined on an equidistant grid . . . . . . . . . . . . . . . . . . . . 226
15.2.3 Defined on a curvilinear grid . . . . . . . . . . . . . . . . . . . . . 228
15.2.4 Space and time varying Charnock coefficients . . . . . . . . . . . . 229
15.2.5 Rainfall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
15.2.6 Defined on a spiderweb grid . . . . . . . . . . . . . . . . . . . . . 230
AF 15.2.7 Combination of several wind specifications . . . . . . . . . . . . . . 233
15.3 Masking of points in the wind grid from interpolation (‘land-sea mask’) . . . . . 235

16 Ice modelling in D-Flow FM 236

16.1 Forced ice cover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
16.2 Dynamic ice cover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
16.2.1 Conservation laws . . . . . . . . . . . . . . . . . . . . . . . . . . 236
16.2.2 Thermodynamics of the ice/snow cover . . . . . . . . . . . . . . . . 237
16.3 Ice effect on wind drag . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
16.4 Ice effect on pressure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
16.5 Ice effect on flow resistance . . . . . . . . . . . . . . . . . . . . . . . . . . 241
DR

16.6 Ice effect on surface exchange . . . . . . . . . . . . . . . . . . . . . . . . 241

16.7 Ice effect on waves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
16.8 Ice input options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
16.8.1 Ice modelling via External . . . . . . . . . . . . . . . . . . . . . 243
16.8.2 Ice modelling via Semtner . . . . . . . . . . . . . . . . . . . . . . 243
16.9 Postprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
16.10 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

17 Coupling to external models via Basic Model Interface (BMI) 247

17.1 BMI interface to interact with the D-Flow FM model state . . . . . . . . . . . 247
17.2 DIMR and the BMI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
17.3 BMI access to hydraulic structure data in D-Flow FM . . . . . . . . . . . . . 248
17.4 BMI access to observations in D-Flow FM . . . . . . . . . . . . . . . . . . . 249
17.5 BMI access to forcings in D-Flow FM . . . . . . . . . . . . . . . . . . . . . 249
17.6 Coupling with D-Waves (SWAN) . . . . . . . . . . . . . . . . . . . . . . . 250
17.6.1 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
17.6.1.1 Input D-Flow FM . . . . . . . . . . . . . . . . . . . . . . 251
17.6.1.2 Input D-Waves . . . . . . . . . . . . . . . . . . . . . . . 252
17.6.1.3 Input DIMR . . . . . . . . . . . . . . . . . . . . . . . . . 253
17.6.1.4 Online process order . . . . . . . . . . . . . . . . . . . . 255
17.6.1.5 Related files . . . . . . . . . . . . . . . . . . . . . . . . 256
17.6.1.6 SWAN output file as input . . . . . . . . . . . . . . . . . 257
17.7 Coupling with D-RTC (FBC-Tools) . . . . . . . . . . . . . . . . . . . . . . . 259
17.7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
17.7.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
17.7.2.1 User interface: the first steps . . . . . . . . . . . . . . . . 260
17.7.2.2 Input D-Flow FM . . . . . . . . . . . . . . . . . . . . . . 261
17.7.2.3 Input D-RTC . . . . . . . . . . . . . . . . . . . . . . . . 261

Deltares viii
 CONTENTS

17.7.2.4 Input DIMR . . . . . . . . . . . . . . . . . . . . . . . . . 261

17.7.2.5 Online process order . . . . . . . . . . . . . . . . . . . . 261
17.8 Coupling with module for Sea Lock Exchange . . . . . . . . . . . . . . . . . 261
17.8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
17.8.2 Coupling of D-Flow FM with ZSF (Sea Lock Exchange) . . . . . . . . 262
17.8.3 Configuration of the model . . . . . . . . . . . . . . . . . . . . . . 263
17.8.4 Processing of the received lateral data items in D-Flow FM . . . . . . 265

18 Water quality and D-Flow FM 267

18.1 Introduction to the coupling of D-Flow FM to D-Water Quality . . . . . . . . . 267

T
18.2 File-based (or offline) coupling of water quality and hydrodynamics . . . . . . 268
18.2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
18.2.2 Creating output for D-Water Quality . . . . . . . . . . . . . . . . . . 268
18.2.3 Limitations and remarks . . . . . . . . . . . . . . . . . . . . . . . 269
18.3 Memory-based (or online) coupling of water quality and hydrodynamics . . . 269
AF 18.3.1 Glossary of terms . . . . . . . . . . . . . . . . . . . . . . .
18.3.2 Definition of the water quality system . . . . . . . . . . . . .
18.3.3 Definition of process parameters . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
269
270
272
18.3.4 Initial conditions, boundary conditions and sources and sinks . . . . . 275
18.3.5 Special options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
18.3.6 Output options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
18.3.7 Running D-Flow FM with processes . . . . . . . . . . . . . . . . . . 281
18.3.8 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
18.3.9 Known issues and limitations . . . . . . . . . . . . . . . . . . . . . 281
18.4 Particle tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
DR

19 Morphology 283

20 Coupling with Nearfield data via COSUMO 284

20.1 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
20.1.1 Run procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
20.1.2 Input DIMR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
20.1.3 COSUMO config file . . . . . . . . . . . . . . . . . . . . . . . . . 289
20.1.4 FF2NF.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
20.1.5 NF2FF.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

21 Calibration and data assimilation 296

21.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
21.2 Getting started with OpenDA . . . . . . . . . . . . . . . . . . . . . . . . . 296
21.3 The OpenDA black box model wrapper for D-Flow FM . . . . . . . . . . . . . 297
21.4 OpenDA configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
21.4.1 Main configuration file and the directory structure . . . . . . . . . . . 297
21.4.2 The algorithm configuration . . . . . . . . . . . . . . . . . . . . 299
21.4.3 The stochObserver configuration . . . . . . . . . . . . . . . . . 299
21.4.3.1 NoosTimeSeriesStochObserver . . . . . . . . . . . . . . 299
21.4.3.2 IoObjectStochObserver . . . . . . . . . . . . . . . . . . . 300
21.4.4 The stochModel configuration . . . . . . . . . . . . . . . . . . . 301
21.4.5 D-Flow FM files and the OpenDA dataObjects configuration . . . . . . 302
21.4.5.1 Start and end time in the model definition file (.mdu) . . . . 303
21.4.5.2 Spatial external forcings (.xyz) . . . . . . . . . . . . . . 303
21.4.5.3 Boundary time series (.tim) . . . . . . . . . . . . . . . . 304
21.4.5.4 Meteorological boundary conditions (<∗.amu>, <∗.amv>,
<∗.amp>) . . . . . . . . . . . . . . . . . . . . . . . . 305
21.4.5.5 Boundary conditions in bc format (.bc) . . . . . . . . . . 305
21.4.5.6 Result time series (<∗_his.nc>) . . . . . . . . . . . . . . 305

Deltares ix
 CONTENTS

21.4.5.7 Restart file (<∗_map.nc>) . . . . . . . . . . . . . . . . . 306

21.4.5.8 Calibration factor definition file (<∗.cld>) . . . . . . . . . . 306
21.4.5.9 Trachytopes roughness definition file (<∗.ttd>) . . . . . . . 307
21.5 Generating noise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
21.6 Examples of the application of OpenDA for D-Flow FM . . . . . . . . . . . . 310
21.6.1 Example 1: Calibration of the roughness parameter . . . . . . . . . . 310
21.6.2 Example 2: EnKF with uncertainty in the tidal components . . . . . . 312
21.6.3 Example 3: EnKF with uncertainty in the inflow velocity . . . . . . . . 313
21.6.4 Example 4: EnKF with uncertainty in the inflow condition for salt . . . 314
21.6.5 Example 5: EnKF with uncertainty on the wind direction . . . . . . . 314

T
21.6.6 Example 6: EnKF with the DCSM v5 model and uncertainty on the
wind direction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

22 Numerical aspects of D-Flow Flexible Mesh 315

22.1 Topological conventions for (2D) horizontal grids . . . . . . . . . . . . . . . 315
AF
22.2 Notation . . . . . . . . . . . . . . . . . . . . . . .
22.3 Definition of bed level options . . . . . . . . . . . . .
22.3.1 Piecewise constant approach for the bed level
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
317
318
318
22.3.2 Piecewise linear approach for the bed levels . . . . . . . . . . . . . 319
22.3.3 Hybrid bed level approach . . . . . . . . . . . . . . . . . . . . . . 320
22.3.4 Specification in the User Interface . . . . . . . . . . . . . . . . . . 320
22.4 The location of open boundaries . . . . . . . . . . . . . . . . . . . . . . . 321
22.4.1 Geometry of open boundaries . . . . . . . . . . . . . . . . . . . . 323
22.4.1.1 Conveyance in 2D . . . . . . . . . . . . . . . . . . . . . 323
22.5 Drying and flooding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
22.5.1 Dry/wet criterion at cell faces . . . . . . . . . . . . . . . . . . . . . 325
DR

22.5.2 Dry/wet criterion at cell circumcenters . . . . . . . . . . . . . . . . 326

22.6 Advection at open boundaries . . . . . . . . . . . . . . . . . . . . . . . . . 326
22.7 Artificial mixing due to sigma-coordinates . . . . . . . . . . . . . . . . . . . 327

23 Tutorial 331
23.1 Tutorial Hydrodynamics for depth-averaged (2D) modelling . . . . . . . . . . 331
23.1.1 Outline of the tutorials . . . . . . . . . . . . . . . . . . . . . . . . 331
23.1.2 Tutorial 1: Creating a curvilinear grid . . . . . . . . . . . . . . . . . 332
23.1.3 Tutorial 2: Creating a triangular grid . . . . . . . . . . . . . . . . . . 336
23.1.4 Tutorial 3: Coupling multiple separate grids . . . . . . . . . . . . . . 339
23.1.5 Tutorial 4: Inserting a bed level . . . . . . . . . . . . . . . . . . . . 341
23.1.6 Tutorial 5: Imposing boundary conditions . . . . . . . . . . . . . . . 344
23.1.7 Tutorial 6: Defining output locations . . . . . . . . . . . . . . . . . . 347
23.1.8 Tutorial 7: Defining computational parameters . . . . . . . . . . . . 348
23.1.9 Tutorial 8: Running a model simulation . . . . . . . . . . . . . . . . 350
23.1.10 Tutorial 9: Viewing the output of a model simulation . . . . . . . . . . 351
23.1.11 Tutorial 10: Exporting a model . . . . . . . . . . . . . . . . . . . . 354
23.1.12 Tutorial 11: Partitioning a model . . . . . . . . . . . . . . . . . . . 355
23.1.13 Tutorial 12: Running a model using a batch script . . . . . . . . . . . 357
23.1.13.1 Sequential on Windows . . . . . . . . . . . . . . . . . . 358
23.1.13.2 Sequential on Linux . . . . . . . . . . . . . . . . . . . . 358
23.1.13.3 Parallel on Windows . . . . . . . . . . . . . . . . . . . . 359
23.1.13.4 Parallel on Linux . . . . . . . . . . . . . . . . . . . . . . 360
23.2 Tutorial Hydrodynamics for 3D modelling . . . . . . . . . . . . . . . . . . . 362
23.2.1 Outline of the tutorials for 3D modelling . . . . . . . . . . . . . . . . 362
23.2.2 Tutorial 13: Set-up of a 3D model, running this model and postpro-
cessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
23.2.3 Tutorial 14: Extra options for postprocessing of 3D model simulations . 369

Deltares x
 CONTENTS

References 375

A The master definition file 381

A.1 Overview of keywords generated by GUI . . . . . . . . . . . . . . . . . . . 381
A.2 Overview of additional keywords for 3D Modelling . . . . . . . . . . . . . . . 391
A.3 Overview of research keywords . . . . . . . . . . . . . . . . . . . . . . . . 392
A.4 Overview of deprecated and removed keywords . . . . . . . . . . . . . . . . 394

B The net file for flexible meshes 397

B.1 2D grids in netCDF UGRID files . . . . . . . . . . . . . . . . . . . . . . . . 397

T
C Attribute files 398
C.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
C.2 Polyline/polygon file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
C.3 Sample file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
C.4 Time series <tim> file (ASCII) . . . . . . . . . . . . . . . . . . . . . . . . 400
AF
C.5 Time-varying data <bc> file (ASCII) . . . . . . . . . .
C.5.1 Name in a bc block . . . . . . . . . . . . . . .
C.5.1.1 Global forcings . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 400
. 403
. 403
C.5.1.2 Boundary forcings . . . . . . . . . . . . . . . . . . . . . 403
C.5.1.3 Meteo forcings on stations . . . . . . . . . . . . . . . . . 404
C.5.1.4 Forcings on "point" locations . . . . . . . . . . . . . . . . 404
C.5.2 Function in a bc block . . . . . . . . . . . . . . . . . . . . . . . . . 404
C.5.3 Quantity names in a bc block . . . . . . . . . . . . . . . . . . . . . 406
C.6 The external forcings file . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
C.6.1 Old style external forcings . . . . . . . . . . . . . . . . . . . . . . 407
DR

C.6.2 New style external forcing . . . . . . . . . . . . . . . . . . . . . . . 410

C.6.2.1 Boundary definitions . . . . . . . . . . . . . . . . . . . . 411
C.6.2.2 Lateral discharge definitions . . . . . . . . . . . . . . . . 412
C.6.2.3 Meteorological forcings . . . . . . . . . . . . . . . . . . . 413
C.6.2.4 Source and sink definitions . . . . . . . . . . . . . . . . . 415
C.6.3 Accepted quantity names . . . . . . . . . . . . . . . . . . . . . . . 416
C.6.4 Overview of deprecated and removed keywords . . . . . . . . . . . 419
C.7 Trachytopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
C.7.1 Area Roughness on Links (ARL-file) . . . . . . . . . . . . . . . . . 420
C.7.1.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . 421
C.7.1.2 Conversion from Delft3D 4 input files . . . . . . . . . . . . 421
C.7.2 Trachytope Definition file (TTD-file) . . . . . . . . . . . . . . . . . . 421
C.7.2.1 General format . . . . . . . . . . . . . . . . . . . . . . . 421
C.7.2.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . 422
C.7.2.3 Discharge dependent format . . . . . . . . . . . . . . . . 422
C.7.2.4 Water level dependent format . . . . . . . . . . . . . . . . 422
C.7.2.5 Supported roughness formulations . . . . . . . . . . . . . 423
C.8 Fixed weirs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
C.9 Calibration Factors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
C.9.1 Calibration factor definition file (CLD-file) . . . . . . . . . . . . . . . 425
C.9.1.1 Header of the CLD-file . . . . . . . . . . . . . . . . . . . 426
C.9.1.2 Constant values . . . . . . . . . . . . . . . . . . . . . . 426
C.9.1.3 Discharge dependent format . . . . . . . . . . . . . . . . 426
C.9.1.4 Water level dependent format . . . . . . . . . . . . . . . . 426
C.9.1.5 Example . . . . . . . . . . . . . . . . . . . . . . . . . . 427
C.9.2 Calibration Class Area on Links (CLL-file) . . . . . . . . . . . . . . . 427
C.9.2.1 Header of the CLL-file . . . . . . . . . . . . . . . . . . . 427
C.9.2.2 Body of the CLL-file . . . . . . . . . . . . . . . . . . . . 427

Deltares xi
 CONTENTS

C.9.2.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . 428

C.10 Sources and sinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
C.11 Dry points and areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
C.12 Structure INI file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
C.12.1 Weir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
C.12.2 Universal Weir . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
C.12.3 Culvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
C.12.4 Long culvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
C.12.5 1D2D Long culvert . . . . . . . . . . . . . . . . . . . . . . . . . . 433
C.12.6 Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

T
C.12.7 Pump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
C.12.8 Orifice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
C.12.9 Gate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
C.12.10 General Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
C.12.11 Dambreak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
AF C.12.12 Compound Structure . . . . . . . . . . . . . . . .
C.12.13 Structure defined with a time series . . . . . . . .
C.12.14 File version history . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
440
441
442
C.13 Space varying wind and pressure . . . . . . . . . . . . . . . . . . . . . . . 442
C.13.1 Meteo on equidistant grids . . . . . . . . . . . . . . . . . . . . . . 443
C.13.2 Curvilinear data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
C.13.3 Spiderweb data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
C.13.4 Meteo on a netCDF file . . . . . . . . . . . . . . . . . . . . . . . . 453
C.14 Statistical output (Fourier, minimum, maximum and average) . . . . . . . . . 453
C.15 Cache file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
C.15.1 File version and description . . . . . . . . . . . . . . . . . . . . . . 457
DR

D Initial conditions and spatially varying input 458

D.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
D.2 Initial and parameter fields . . . . . . . . . . . . . . . . . . . . . . . . . . 458
D.3 Supported quantities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
D.3.1 Accepted quantity names in initial field files . . . . . . . . . . . . . . 460
D.3.2 Water levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
D.3.3 Initial velocities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
D.3.4 Salinity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
D.3.5 Temperature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
D.3.6 Tracers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
D.3.7 Sediment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
D.3.8 Physical coefficients . . . . . . . . . . . . . . . . . . . . . . . . . 463
D.4 Supported file formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
D.4.1 Inside-polygon option . . . . . . . . . . . . . . . . . . . . . . . . . 464
D.4.2 Sample file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
D.4.3 GeoTIFF file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
D.4.4 Vertical profile file . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
D.4.5 Map file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
D.4.6 Restart file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

E Boundary conditions specification 466

E.1 Supported boundary types . . . . . . . . . . . . . . . . . . . . . . . . . . 466
E.1.1 Open boundaries . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
E.1.2 Astronomic boundary conditions . . . . . . . . . . . . . . . . . . . 466
E.1.3 Astronomic correction factors . . . . . . . . . . . . . . . . . . . . . 466
E.1.4 Harmonic flow boundary conditions . . . . . . . . . . . . . . . . . . 466
E.1.5 QH-relation flow boundary conditions . . . . . . . . . . . . . . . . . 467

Deltares xii
 CONTENTS

E.1.6 Time-series flow boundary conditions . . . . . . . . . . . . . . . . . 467

E.1.7 Time-series transport boundary conditions . . . . . . . . . . . . . . 467
E.1.8 Time-series for the heat model parameters . . . . . . . . . . . . . . 467
E.1.9 Time-series for varying air density . . . . . . . . . . . . . . . . . . 468
E.2 Boundary signal file formats . . . . . . . . . . . . . . . . . . . . . . . . . . 468
E.2.1 The <cmp> format . . . . . . . . . . . . . . . . . . . . . . . . . 468
E.2.2 The <qh> format . . . . . . . . . . . . . . . . . . . . . . . . . . 468
E.2.3 The <bc> format . . . . . . . . . . . . . . . . . . . . . . . . . . 468
E.2.4 The netCDF-format . . . . . . . . . . . . . . . . . . . . . . . . . . 469
E.2.4.1 Scalar quantity for point-location time-series . . . . . . . . 469

T
E.2.4.2 Scalar Quantity for gridded data . . . . . . . . . . . . . . 469
E.2.4.3 Vector quantity . . . . . . . . . . . . . . . . . . . . . . . 471

F Output files 473

F.1 Diagnostics file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
AF
F.2 Demanding output . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
F.2.1 The MDU-file . . . . . . . . . . . . . . . . . . . . . . . . . . . .
F.2.2 Observation points . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
473
474
474
F.2.2.1 The observation point file with extension <∗_obs.ini> . . . 474
F.2.2.2 The observation point file with extension <∗.xyn> . . . . . 475
F.2.3 Moving observation points . . . . . . . . . . . . . . . . . . . . . . 476
F.2.4 Observation cross sections . . . . . . . . . . . . . . . . . . . . . . 477
F.2.4.1 Observation cross section file with extension <∗_crs.pli> . 477
F.3 NetCDF output files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
F.3.1 Timeseries as netCDF his-file . . . . . . . . . . . . . . . . . . . . . 479
F.3.1.1 Dimensions . . . . . . . . . . . . . . . . . . . . . . . . 479
DR

F.3.1.2 Location variables . . . . . . . . . . . . . . . . . . . . . 479

F.3.1.3 Overview of output quantities in a netCDF his-file . . . . . . 480
F.3.1.4 Variables on stations . . . . . . . . . . . . . . . . . . . . 482
F.3.1.5 Variables on cross sections . . . . . . . . . . . . . . . . . 489
F.3.1.6 Mass balance output . . . . . . . . . . . . . . . . . . . . 491
F.3.1.7 Variables on sources/sinks . . . . . . . . . . . . . . . . . 494
F.3.1.8 Hydraulic structure output . . . . . . . . . . . . . . . . . 494
F.3.1.9 Geometry variables . . . . . . . . . . . . . . . . . . . . 505
F.3.2 Spatial fields as netCDF map-file . . . . . . . . . . . . . . . . . . . 506
F.3.3 Class map files as netCDF clm-file . . . . . . . . . . . . . . . . . . 523
F.3.4 Restart files as netCDF rst-file . . . . . . . . . . . . . . . . . . . . 523
F.3.5 Volume tables per- gridpoint output as netCDF file . . . . . . . . . . 523
F.3.6 NetCDF versions and file formats . . . . . . . . . . . . . . . . . . . 526
F.4 Shapefiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
F.5 Post processing on his-file . . . . . . . . . . . . . . . . . . . . . . . . . . 526
F.5.1 Max25 function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
F.5.2 Maximum based on a generic filter . . . . . . . . . . . . . . . . . . 527
F.5.3 Maximum based on a running mean filter . . . . . . . . . . . . . . . 527

G Model generation 528

G.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
G.2 Grid generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
G.2.1 Uniform Cartesian grid . . . . . . . . . . . . . . . . . . . . . . . . 528
G.2.2 Locally refined Cartesian grid . . . . . . . . . . . . . . . . . . . . . 528

H Spatial editor 529

H.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
H.2 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529

Deltares xiii
 CONTENTS

H.2.1 Overview of spatial editor . . . . . . . . . . . . . . . . . . . . . . . 529

H.2.2 Import/export dataset . . . . . . . . . . . . . . . . . . . . . . . . . 530
H.2.3 Activate (spatial) model quantity . . . . . . . . . . . . . . . . . . . 531
H.2.4 Colorscale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
H.2.5 Render mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
H.2.6 Context menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
H.3 Quantity selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
H.4 Geometry operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
H.4.1 Polygons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
H.4.2 Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537

T
H.4.3 Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
H.5 Spatial operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
H.5.1 Import point cloud . . . . . . . . . . . . . . . . . . . . . . . . . . 539
H.5.2 Crop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
H.5.3 Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
AF H.5.4 Set value . . . . . . . . . . . .
H.5.5 Contour . . . . . . . . . . . .
H.5.6 Copy to samples . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
541
542
544
H.5.7 Copy to spatial data . . . . . . . . . . . . . . . . . . . . . . . . . 545
H.5.8 Merge spatial data . . . . . . . . . . . . . . . . . . . . . . . . . . 546
H.5.9 Gradient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
H.5.10 Interpolate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
H.5.11 Smoothing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
H.5.12 Overwrite (single) value . . . . . . . . . . . . . . . . . . . . . . . . 553
H.6 Operation stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
H.6.1 Stack workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
DR

H.6.2 Edit operation properties . . . . . . . . . . . . . . . . . . . . . . . 555

H.6.3 Enable/disable operations . . . . . . . . . . . . . . . . . . . . . . 556
H.6.4 Delete operations . . . . . . . . . . . . . . . . . . . . . . . . . . . 557
H.6.5 Refresh stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
H.6.6 Quick links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
H.6.7 Import/export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559

Deltares xiv
 List of Tables

List of Tables
3.1 Fitting coefficients for wave/current boundary layer model . . . . . . . . . . . 28

6.1 Functions and their descriptions within the scripting ribbon of the User Inter-
face. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
6.1 Functions and their descriptions within the scripting ribbon of the User Inter-
face. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
6.2 Shortcut keys within the scripting editor of the User Interface. . . . . . . . . . 61
6.2 Shortcut keys within the scripting editor of the User Interface. . . . . . . . . . 62

T
7.1 Overview and description of numerical parameters . . . . . . . . . . . . . . 116
7.2 Input and output parameters of the example . . . . . . . . . . . . . . . . . . 119
7.3 Time (after Reference Date in seconds) of output files . . . . . . . . . . . . . 119
7.4 Overview and description miscellaneous parameters . . . . . . . . . . . . . 120
7.5 Overview and description of Z-layer parameters . . . . . . . . . . . . . . . . 121
AF
12.1 Recommended values of input parameters in the Verheij–Van der Knaap (2002)
formula. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
12.2 Recommended values for uc and τc . . . . . . . . . . . . . . . . . . . . . . 177
12.3 Values of coefficients c1 , c2 and Bmax of the Van der Knaap (2000) formula for
different material types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
12.4 Mapping table for weir input parameters to general structure parameters . . . 189
12.5 Mapping table for orifice input parameters to general structure parameters . . 191

16.1 Ice input keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

16.2 ice quantities on map output file . . . . . . . . . . . . . . . . . . . . . . . . 245
DR

17.1 Supported compound variable fields for hydraulic structures in D-Flow FM via
BMI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
17.2 Supported compound variable fields for observations in D-Flow FM via BMI. . 249
17.3 Supported compound variable fields for forcings in D-Flow FM via BMI. . . . . 249
17.4 Entries in ExtForceFile for use with wavemodel 7. The entries in the
Varname column that should be present in the NetCDF file depend on the
Waveforcing value in the .mdu file. . . . . . . . . . . . . . . . . . . . . 259

18.1 File-based versus memory-based D-Water Quality processes in D-Flow FM. . 267
18.2 Various types of parameter inputs for water quality models in D-Flow FM. . . . 273
18.3 Data from D-Flow FM that are available for water quality processes . . . . . . 275

21.1 Directory structure of the OpenDA Ensemble Kalman filtering configuration for
the simple Waal D-Flow FM model. . . . . . . . . . . . . . . . . . . . . . . 298
21.2 D-Flow FM files that can be manipulated and the corresponding OpenDA class
names to be used in the <dflowfmWrapper.xml> file. . . . . . . . . . . . . . 302

A.1 Standard MDU-file with default settings. . . . . . . . . . . . . . . . . . . . . 381

A.2 Keywords in MDU-file for 3D modelling not in the GUI yet. . . . . . . . . . . . 392
A.3 Overview of numerical research parameters with compulsory defaults. . . . . 392
A.4 Overview of deprecated and removed keywords. . . . . . . . . . . . . . . . 395

C.1 Description of <bc> format. . . . . . . . . . . . . . . . . . . . . . . . . . 400

C.3 Quantity names for use in <*.bc> files. . . . . . . . . . . . . . . . . . . . . 406
C.4 Definition of external forcings. . . . . . . . . . . . . . . . . . . . . . . . . . 410
C.5 Boundary definitions in new style external forcing file. . . . . . . . . . . . . . 411
C.6 Lateral discharge definitions in new style external forcing file. . . . . . . . . . 412
C.7 Meteorological forcings in new style external forcing file. . . . . . . . . . . . 413

Deltares xv
 List of Tables

C.8 Source and sink definitions in new style external forcing file. . . . . . . . . . . 415
C.9 List of accepted external forcing quantity names. . . . . . . . . . . . . . . . 416
C.10 Deprecated and obsolete keywords in external forcings file. . . . . . . . . . 419
C.12 General part of structure file. . . . . . . . . . . . . . . . . . . . . . . . . . 429
C.13 Weir definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
C.14 Universal Weir definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
C.15 Culvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
C.16 Long culvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
C.17 Long culvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
C.18 Bridge Structure definition. . . . . . . . . . . . . . . . . . . . . . . . . . . 434

T
C.19 Pump definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
C.20 Orifice definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
C.21 Gate definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
C.22 Specific input for the general structure. . . . . . . . . . . . . . . . . . . . . 437
C.23 Specific input for the dambreak. . . . . . . . . . . . . . . . . . . . . . . . . 438
AF
C.24
C.25
Specific input for the compound structure. . . . . . . . . .
Quantities that can be set by a time series. . . . . . . . .
. . .
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
440
442

D.1 Initial and parameter fields. . . . . . . . . . . . . . . . . . . . . . . . . . . 458

D.2 List of accepted field quantity names in initial field file. . . . . . . . . . . . . . 461

F.1 Definition of observation points. . . . . . . . . . . . . . . . . . . . . . . . . 474

F.2 Global overview of output quantities in the history file. . . . . . . . . . . . . . 481
F.3 Output quantities of observation stations in history file. . . . . . . . . . . . . 483
F.4 Output quantities on cross sections in history file. . . . . . . . . . . . . . . . 490
F.5 Output quantities for the mass balance in history file. . . . . . . . . . . . . . 492
DR

F.6 Output quantities of pumps in history file. . . . . . . . . . . . . . . . . . . . 494

F.7 Output quantities of general structures in history file. . . . . . . . . . . . . . 495
F.8 Output quantities of weirs in history file. . . . . . . . . . . . . . . . . . . . . 497
F.9 Output quantities of orifices in history file. . . . . . . . . . . . . . . . . . . . 498
F.10 Output quantities of bridges in history file. . . . . . . . . . . . . . . . . . . . 499
F.11 Output quantities of culverts in history file. . . . . . . . . . . . . . . . . . . 500
F.12 Output quantities of long culverts in history file. . . . . . . . . . . . . . . . . 500
F.13 Output quantities of dam breaks in history file. . . . . . . . . . . . . . . . . 501
F.14 Output quantities of universal weirs in history file. . . . . . . . . . . . . . . . 502
F.15 Output quantities of compound structures in history file. . . . . . . . . . . . . 503
F.16 Summary of output in history files of quantities for different structures. . . . . . 504
F.17 Output variables in map file of UGRID format. Column ’Location’ shows the
grid location: CN means cell corners. L means net links. S means pressure
points, U means velocity points. S3D and U3D are the corresponding locations
in 3D networks. Two more locations in 3D networks are: W, vertical velocity
point on all layer interfaces, and WU, vertical viscosity point on all layer inter-
faces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
F.18 Flow analysis variables in the map file . . . . . . . . . . . . . . . . . . . . . 522
F.19 Features and MDU settings for generating shapefiles . . . . . . . . . . . . . 526

Deltares xvi
 List of Figures

List of Figures
3.1 Input for map projection for specifying Coriolis parameter on the grid. . . . . . 12
3.2 Input parameters for horizontal and vertical eddy viscosities. . . . . . . . . . 13
3.3 Vertical profile secondary flow (v ) in river bend and direction bed stress . . . . 18
3.4 Schematic view of non-linear interaction of wave and current bed shear-stresses
(from Soulsby et al. (1993b, Figure 16, p. 89)) . . . . . . . . . . . . . . . . . 27
3.5 Inter-comparison of eight models for prediction of mean and maximum bed
shear-stress due to waves and currents (from Soulsby et al. (1993b, Figure 17,
p. 90)) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

T
5.1 Overview of the heat exchange mechanisms at the surface . . . . . . . . . . 41
5.2 Co-ordinate system position Sun
δ : declination; θ: latitude; ωt: angular speed . . . . . . . . . . . . . . . . . 45
6.1 Start-up lay-out D-Flow FM User Interface . . . . . . . . . . . . . . . . . . 52
AF
6.2
6.3
6.4
Project window of D-Flow FM plugin . . . . . . . . . . . . . . . .
The central window with a map and contents of the D-Flow FM model
The model Settings window with General settings tab enabled . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
53
54
54
6.5 Map window controlling map contents . . . . . . . . . . . . . . . . . . . . . 55
6.6 Log of messages, warnings and errors in message window . . . . . . . . . . 55
6.7 Time Navigator window in D-Flow FM User Interface . . . . . . . . . . . . . 55
6.8 Docking windows on two screens within the User Interface. . . . . . . . . . . 56
6.9 Bringing the Time Navigator window to the front . . . . . . . . . . . . . . . 56
6.10 Docking the Time Navigator window. . . . . . . . . . . . . . . . . . . . . . 56
6.11 Auto hide the Properties window . . . . . . . . . . . . . . . . . . . . . . . 57
DR

6.12 Perform operations using the shortcut keys . . . . . . . . . . . . . . . . . . 57

6.13 The File ribbon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6.14 The User Interface options dialog. . . . . . . . . . . . . . . . . . . . . . . . 58
6.15 The Home ribbon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.16 The View ribbon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.17 The Tools ribbon contains just the Data item. . . . . . . . . . . . . . . . . . 59
6.18 The Map ribbon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.19 The scripting ribbon within the User Interface. . . . . . . . . . . . . . . . . . 60
6.20 The quick access toolbar. . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.21 Set map coordinate system using right mouse button . . . . . . . . . . . . . 63
6.22 Select a coordinate system using the quick search bar . . . . . . . . . . . . 64
6.23 Perform operations using the shortcut keys . . . . . . . . . . . . . . . . . . 65

7.1 The Add Model drop-down menu . . . . . . . . . . . . . . . . . . . . . . . 68

7.2 The Select model ... window . . . . . . . . . . . . . . . . . . . . . . . . . 68
7.3 Overview of general tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
7.4 Coordinate system wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
7.5 Overview of geographical features . . . . . . . . . . . . . . . . . . . . . . 70
7.6 Overview of map ribbon . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
7.7 Example of expanded Estimated Grid-snapped features attribute in the Map
window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
7.8 Example of grid snapped features displayed on the central map . . . . . . . . 72
7.9 Geographical and grid snapped representation of an observation point . . . . 72
7.10 Attribute table with observation points . . . . . . . . . . . . . . . . . . . . . 73
7.11 Geographical and grid snapped representation of a cross section . . . . . . . 73
7.12 Attribute table with observation cross sections . . . . . . . . . . . . . . . . 74
7.13 Geographical and grid snapped representation of a thin dam . . . . . . . . . 74
7.14 Attribute table with thin dams . . . . . . . . . . . . . . . . . . . . . . . . . 75
7.15 Geographical and grid snapped representation of a fixed weir . . . . . . . . . 75

Deltares xvii
 List of Figures

7.16 Schematic representation of a fixed weir . . . . . . . . . . . . . . . . . . . 75

7.17 Attribute table with fixed weirs . . . . . . . . . . . . . . . . . . . . . . . . . 76
7.18 Fixed weir editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
7.19 Geographical representation of a land boundary . . . . . . . . . . . . . . . 77
7.20 Attribute table with land boundaries . . . . . . . . . . . . . . . . . . . . . . 77
7.21 Geographical and grid snapped representation of several dry points . . . . . . 78
7.22 Attribute table with dry points . . . . . . . . . . . . . . . . . . . . . . . . . 79
7.23 Geographical and grid snapped representation of a dry area . . . . . . . . . 79
7.24 Attribute table with dry areas . . . . . . . . . . . . . . . . . . . . . . . . . 80
7.25 Polygon for pump (a) and adjustment of physical properties (b). . . . . . . . . 80

T
7.26 Selection of the pumps . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
7.27 Polygon for adjustable weir (a) and adjustment of geometrical and temporal
conditions (b). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
7.28 Time series for crest level. . . . . . . . . . . . . . . . . . . . . . . . . . . 82
7.29 Time series for crest level. . . . . . . . . . . . . . . . . . . . . . . . . . . 82
AF
7.30
7.31
7.32
Polygon for gate (a) and adjustment of geometrical and temporal conditions (b). 83
Selection of a bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Adjustment of the properties of the pillars . . . . . . . . . . . . . . . . . . . 84
7.33 Bed level activated in the spatial editor . . . . . . . . . . . . . . . . . . . . 85
7.34 Overview time frame tab . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
7.35 Relation between Reference Date and the simulation start and stop time for
astronomic- and harmonic-series as used in the simulation. Time-series should
cover the simulation time. . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
7.36 Overview processes tab . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
7.37 Initial conditions in the Project window . . . . . . . . . . . . . . . . . . . . 87
7.38 The ‘Initial Conditions’ tab where you can specify the uniform values and the
DR

layer distributions of the active physical quantities. . . . . . . . . . . . . . . 88

7.39 Initial water levels activated in the spatial editor . . . . . . . . . . . . . . . . 88
7.40 Selecting 3 dimensional initial fields from the dropdown box in the ‘Map’ ribbon
to edit them in the spatial editor . . . . . . . . . . . . . . . . . . . . . . . . 88
7.41 Restart files in output states folder . . . . . . . . . . . . . . . . . . . . . . 89
7.42 Restart file in initial conditions attribute . . . . . . . . . . . . . . . . . . . . 89
7.43 Adding a boundary support point on a polyline in the central map . . . . . . . 90
7.44 Polyline added in Project window under ‘Boundary Conditions’ . . . . . . . . 90
7.45 Geometry edit options in Map ribbon . . . . . . . . . . . . . . . . . . . . . 90
7.46 Edit name of polyline/boundary in Boundaries tab . . . . . . . . . . . . . . . 91
7.47 Overview of the boundary data editor . . . . . . . . . . . . . . . . . . . . . 92
7.48 Process and quantity selection in the boundary data editor . . . . . . . . . . 93
7.49 Activate a support point . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
7.50 Time zone in the Boundary conditions editor . . . . . . . . . . . . . . . . . 94
7.51 Specification of time series in the boundary data editor (left panel) . . . . . . 95
7.52 Window for generating series of time points . . . . . . . . . . . . . . . . . . 95
7.53 Csv import wizard: csv file selection . . . . . . . . . . . . . . . . . . . . . . 96
7.54 Clipboard/csv import wizard: specification of how data should be parsed into
columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
7.55 Clipboard/csv import wizard: specification of how values should be parsed and
columns should be mapped . . . . . . . . . . . . . . . . . . . . . . . . . . 98
7.56 Specification of harmonic components in boundary data editor . . . . . . . . 99
7.57 Selection of astronomical components from list (after pressing ‘select compo-
nents’) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
7.58 Suggestions for astronomical components in list . . . . . . . . . . . . . . . 101
7.59 Editing harmonic/astronomic components and their corrections . . . . . . . . 101
7.60 Specification of a Q-h relationship . . . . . . . . . . . . . . . . . . . . . . . 102

Deltares xviii
 List of Figures

7.61 Selection of vertically uniform or varying boundary conditions in case of a 3D

model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
7.62 Overview of the layer view component of the boundary conditions editor . . . 103
7.63 Specification of boundary forcing data (in this example for salinity) at 3 posi-
tions in the vertical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
7.64 Example of active and total signal for multiple water level data series on one
support point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
7.65 Importing or exporting boundary features — both polylines <∗.pli> and forc-
ing <∗.bc> — from the Project window using the right mouse button . . . . . 104
7.66 Import or export a <∗.pli>-file as is or with coordinate transformation. . . . . 104

T
7.67 Import or export a <∗.pli>-file as is or with coordinate transformation. . . . . 105
7.68 Import or export a *.pli file as is or with coordinate transformation. . . . . . . . 106
7.69 Overview of all boundary conditions in attribute table . . . . . . . . . . . . . 107
7.70 The physical parameters in the Project window . . . . . . . . . . . . . . . . 107
7.71 The section of the ‘Physical Parameters’ tab where you can specify roughness
AF related parameters and formulations. . . . . . . . . . . . . . . . . . . . . .
7.72 Roughness activated in the spatial editor to create/edit a spatially varying field
7.73 The section of the‘Physical Parameters’ tab where you can specify (uniform)
108
108

values for the horizontal and vertical eddy viscosity and diffusivity. . . . . . . . 109
7.74 Viscosity activated in the spatial editor to create/edit a spatially varying field . . 109
7.75 Overview of parameters in sub-tab Wind . . . . . . . . . . . . . . . . . . . 110
7.76 Activate the sources and sinks editing icon in the Map ribbon . . . . . . . . . 111
7.77 Add sources and sinks in the central map using the ‘Sources and sinks’ icon. . 111
7.78 Sources and sinks appearing in the Project window . . . . . . . . . . . . . . 112
7.79 Specifying time series for sources and sinks in the sources and sinks editor . . 112
7.80 Output Parameters tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
DR

7.81 Overview Output Parameters tab . . . . . . . . . . . . . . . . . . . . . . . 117

7.82 Specification of sigma-layers . . . . . . . . . . . . . . . . . . . . . . . . . 120
7.83 Specification of Z-layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
7.84 Model/data import drop-down menu . . . . . . . . . . . . . . . . . . . . . . 122
7.85 Model/data import wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

8.1 Selecting the model you want to run in the Project window . . . . . . . . . . 123
8.2 Group Run in Home ribbon . . . . . . . . . . . . . . . . . . . . . . . . . . 123
8.3 Run console D-Flow FM User Interface . . . . . . . . . . . . . . . . . . . . 124
8.4 Partioning exporter dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
8.5 Domain selector in Delft3D-QUICKPLOT for partitioned map files. . . . . . . . 133

9.1 Example of setting output (in)visible in the Map window . . . . . . . . . . . . 142

9.2 Useful map visualization options in the Delft3D-QUICKPLOT . . . . . . . . . 143

10.1 Example of σ -model (left) and Z -model (right). . . . . . . . . . . . . . . . . 146

10.2 Vertical grid numbering, for a σ -model (left) and a z-coordinate model (right) . 146
10.3 Illustration of the different layering concepts of D-Flow FM: a) σ -layering; b)
z-layering; c) z-σ -layering with NumTopSigUniform = 1; d) z-σ -layering
with NumTopSigUniform = 0. . . . . . . . . . . . . . . . . . . . . . . 149
10.4 Illustration of spurious oscillations in horizontal currents near open boundaries 157
10.5 Illustration of monitor for occurrence of spurious oscillations . . . . . . . . . . 158

11.1 User Interface view of a simple channel covered by a straightforward Cartesian

grid. Boundary conditions are prescribed at the left hand side and the right
hand size of the domain. . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
11.2 Transitioning between initial conditions Fi and boundary forcing Fb depending
on the smoothing time Tsmo and smoothing start time Tstart,smo for a case in
which the start of start time TStart falls within the smoothing period. . . . . 168

Deltares xix
 List of Figures

11.3 Cell-centre velocity magnitude along the streamwise direction of an idealized

normal-flow case. ExtrBl = 1 extrapolates the bed levels at the boundaries
and perfect normal flow is obtained. . . . . . . . . . . . . . . . . . . . . . . 170
11.4 Flow depth at velocity points along the streamwise direction of an idealized
normal-flow case. ExtrBl = 1 extrapolates the bed levels at the boundaries
and perfect normal flow is obtained. . . . . . . . . . . . . . . . . . . . . . . 170
11.5 Cell-centre flow depth along the streamwise direction of an idealized normal-
flow case. ExtrBl = 1 extrapolates the bed levels at the boundaries and
perfect normal flow is obtained. . . . . . . . . . . . . . . . . . . . . . . . . 171

T
12.1 Selection of structures (and other items) in the toolbar. . . . . . . . . . . . . 172
12.2 General structure, side view . . . . . . . . . . . . . . . . . . . . . . . . . . 180
12.3 General structure, top view . . . . . . . . . . . . . . . . . . . . . . . . . . 180
12.4 General structure, front view . . . . . . . . . . . . . . . . . . . . . . . . . 181
12.5 Submerged gate flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
AF
12.6 Submerged weir-flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.7 Input for a gate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.8 Side view of a culvert . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
186
190
192
12.9 Good modelling practice, culvert, Inverted Siphon and Siphon . . . . . . . . . 194
12.10 Side view of an inverted siphon . . . . . . . . . . . . . . . . . . . . . . . . 195
12.11 Side view of a culvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
12.12 A suspension bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
12.13 Crest level (Y-Z) profile of a Universal weir, divided into three rectangular weir
sections (2, 4 and 6) and four triangular weir sections (1, 3, 5 and 7) . . . . . 199
12.14 Pump station . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
DR

13.1 Conceptual schematization of the modelling environment, visualizing the Ba-

sic Model Interface connecting the D-Flow FM model for hydrodynamic and
morphodynamic computation with the Python environment for vegetation and
ecological modelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

15.1 Nautical conventions for the wind. . . . . . . . . . . . . . . . . . . . . . . 219

15.2 Prescription of the dependency of the wind drag coefficient Cd on the wind
speed is achieved by means of at least 1 point, with a maximum of 3 points. . 220
15.3 Grid definition of the spiderweb grid for cyclone winds. . . . . . . . . . . . . 231

16.1 Conceptual diagram of the ice-growth (left) and temperature (right) model . . . 237
16.2 Illustration of computed ice thickness in case of no snow (in blue), ice thickness
in case of snow (in green) and snow thickness (in red) . . . . . . . . . . . . 245

17.1 An Integrated model in the Project window . . . . . . . . . . . . . . . . . . 260

17.2 Example of a Control flow in D-RTC . . . . . . . . . . . . . . . . . . . . . . 260
17.3 An example of a simple D-Flow FM model in the Graphic User Interface (GUI).
The sea lock is in the middle, the lake on the left side and the sea on the right
side. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

18.1 General overview of substances included in D-Water Quality . . . . . . . . . 272

21.1 Visualisation of the EnKF computation results from OpenDA for a certain ob-
servation point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

22.1 Flexible mesh topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

22.2 Two conventional definitions of the cell center of a triangle: the circumcenter
and the mass center. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

Deltares xx
 List of Figures

22.3 Perfect orthogonality and nearly perfect smoothness along the edge connect-
ing two triangles. Black lines/dots are network links/nodes, blue lines/dots are
flow links/nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
22.4 Poor mesh properties due to violating either the smoothness or the orthogo-
nality at the edge connecting two triangles . . . . . . . . . . . . . . . . . . 317
22.5 Definition of the water levels, the bed levels and the velocities in case of two
adjacent triangular cells. . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
22.6 Specification of the conveyance option in the User Interface. . . . . . . . . . 320
22.7 Specification of the bed level treatment type in the User Interface. . . . . . . . 320
22.8 Specification of the hybrid bed options (with keywords blminabove and

T
blmeanbelow). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
22.9 Virtual boundary ’cells’ near the shaded boundary . . . . . . . . . . . . . . 321
22.10 Position of virtual boundary point . . . . . . . . . . . . . . . . . . . . . . . 322
22.11 Bed representation with uniform depth levels (a), and locally sloping bed (b). . 323
22.12 A shematic view of the linear variation over the width for calculating the flow
AF parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
22.13 Example of a hydrostatic consistent and inconsistent grid; (a) Hδσ > σ ∂H
(b) Hδσ < σ ∂H ∂x
∂x
δx,
. 324

δx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
22.14 Finite Volume for diffusive fluxes and pressure gradients . . . . . . . . . . . 328
22.15 Left and right approximation of a strict horizontal gradient . . . . . . . . . . . 328

23.1 Start RGFGRID by a double-click on Grid. . . . . . . . . . . . . . . . . . . 332

23.2 Splines in Tutorial01 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
23.3 Settings for the Grow Grid from Splines procedure. . . . . . . . . . . . . . . 333
23.4 Generated curvilinear grid after the new Grow Grid from Splines procedure. . 334
23.5 Orthogonality of the generated curvilinear grid after the Grow Grid from Splines
DR

procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
23.6 Importing a land boundary . . . . . . . . . . . . . . . . . . . . . . . . . . 336
23.7 After closing RGFGRID the grid is visible in the Delft3D Flexible Mesh Suite
GUI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
23.8 Polygon that envelopes the area in which an unstructured grid is aimed to be
established. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
23.9 Unstructured grid, after having refined the polygon. . . . . . . . . . . . . . . 338
23.10 Connection of the river grid and the unstructured grid. The red lines show the
inserted grid lines used to couple the two grids manually. . . . . . . . . . . . 340
23.11 Orthogonality of the integrated grid, containing the curvilinear part, the trian-
gular part and the coupling between the two grids. . . . . . . . . . . . . . . 341
23.12 Map-ribbon with the Spatial Operations menu. . . . . . . . . . . . . . . . . 342
23.13 Activate import samples 1. . . . . . . . . . . . . . . . . . . . . . . . . . . 342
23.14 Interpolated bed levels values at the grid (estuary). . . . . . . . . . . . . . . 342
23.15 Polygon drawn to around the missing depths in the harbour. . . . . . . . . . . 343
23.16 Interpolated bed levels values at the grid (harbour). . . . . . . . . . . . . . 343
23.17 Location of the two open boundaries at the sea and river side. . . . . . . . . 345
23.18 Selection of Boundary01. . . . . . . . . . . . . . . . . . . . . . . . . . . 345
23.19 Boundary conditions seaside. . . . . . . . . . . . . . . . . . . . . . . . . 346
23.20 Boundary condition riverside. . . . . . . . . . . . . . . . . . . . . . . . . . 346
23.21 Overview cross sections and observation points. . . . . . . . . . . . . . . . 348
23.22 The time frame of the simulation. . . . . . . . . . . . . . . . . . . . . . . . 349
23.23 Imposed initial conditions for the simulation. . . . . . . . . . . . . . . . . . 349
23.24 Optional output parameters for the computation. . . . . . . . . . . . . . . . 349
23.25 Menu for saving a project. . . . . . . . . . . . . . . . . . . . . . . . . . . 350
23.26 View of Delft3D Flexible Mesh Suite when running a model. . . . . . . . . . 351
23.27 View of Delft3D Flexible Mesh Suite, available to select a location for time-
series in. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

Deltares xxi
 List of Figures

23.28 View of Delft3D Flexible Mesh Suite, time-series for observation point ”water
level at Borsele”. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
23.29 WMS layer icon at the top of the map-tree viewer. . . . . . . . . . . . . . . 353
23.30 View of Delft3D Flexible Mesh Suite in combination with OpenStreetMap. . . 353
23.31 Select waterlevel(s1) from the map tree . . . . . . . . . . . . . . . . . . . . 353
23.32 Layer properties editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
23.33 Menu for exporting a project. . . . . . . . . . . . . . . . . . . . . . . . . . 355
23.34 Model domain with a shelf break. . . . . . . . . . . . . . . . . . . . . . . . 363
23.35 Specification of Z-sigma layers . . . . . . . . . . . . . . . . . . . . . . . . 364
23.36 Icon for grid selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

T
23.37 Location of 2DV cross section. . . . . . . . . . . . . . . . . . . . . . . . . 365
23.38 Overall 2DV cross section of salinity including layer interfaces. . . . . . . . . 366
23.39 2DV cross section of salinity including layer interfaces at shelf break. . . . . . 367
23.40 2DV cross section of salinity including layer interfaces at deep part. . . . . . 368
23.41 Location of 2DV cross section. . . . . . . . . . . . . . . . . . . . . . . . . 369
AF
23.42 Location of 2DV cross section. . . . . . . . . . . . . . . . . . . . . . . .
23.43 2DV cross sectional view of salinity. . . . . . . . . . . . . . . . . . . . .
23.44 2DV cross sectional view of vertical eddy viscosity. . . . . . . . . . . . . .
.
.
.
370
371
372
23.45 Time history of salinity near surface and near bed. . . . . . . . . . . . . . . 373
23.46 ZT plot of salinity at 24 m from inflow boundary. . . . . . . . . . . . . . . . 374

C.1 Illustration of the data to grid conversion for meteo input on a separate curvi-
linear grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
C.2 Wind definition according to Nautical convention . . . . . . . . . . . . . . . 451
C.3 Spiderweb grid definition . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
DR

H.1 Overview of spatial editor functionality in Map ribbon . . . . . . . . . . . . . 529

H.2 Importing a point cloud into the project using the context menu on “project” in
the project tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
H.3 Importing a point cloud into the project using the "Import" drop-down menu in
the Spatial Operations ribbon . . . . . . . . . . . . . . . . . . . . . . . . . 531
H.4 Activate the imported point cloud in the spatial editor by double clicking it in
the project tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
H.5 Activate the imported point cloud in the spatial editor by selecting it from the
dropdown box in the Map ribbon . . . . . . . . . . . . . . . . . . . . . . . 531
H.6 Legend button in Map ribbon . . . . . . . . . . . . . . . . . . . . . . . . . 532
H.7 Activate the colorscale using the Legend in the map ribbon . . . . . . . . . . 532
H.8 Edit the colorscale properties using the context menu on the active layer in the
Map Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
H.9 Select the rendermode for the active layer in the property grid. . . . . . . . . 534
H.10 Example of a coverage rendered as colored numbers. . . . . . . . . . . . . 534
H.11 Selecting a smoothing operation for a polygon geometry from the context
menu (using context menu) . . . . . . . . . . . . . . . . . . . . . . . . . . 535
H.12 Activating a spatial quantity by double clicking it in the project tree (in this
example ‘Initial Water Level’) . . . . . . . . . . . . . . . . . . . . . . . . . 535
H.13 Activating a spatial quantity by selecting it from the dropdown box in the ‘Spa-
tial Operations’ ribbon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
H.14 Overview of the available geometry operations in the ‘Spatial Operations’ ribbon536
H.15 Activating the polygon operation and drawing polygons in the central map. . . 537
H.16 Activating the line operation and drawing lines in the central map. . . . . . . . 537
H.17 Activating the ‘Add points’ operation, drawing them in the central map and
assigning a value to them. . . . . . . . . . . . . . . . . . . . . . . . . . . 538
H.18 Overview of the available spatial operations in the ‘Spatial Operations’ ribbon . 538

Deltares xxii
 List of Figures

H.19 Importing a point cloud using the ‘Import’ operation from the ‘Spatial Opera-
tions’ ribbon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
H.20 Option to perform a coordinate transformation on the imported point cloud . . 539
H.21 Appearance of import point cloud operation in the operations stack . . . . . . 539
H.22 Performing a crop operation on a point cloud with a polygon using ‘Crop’ from
the ‘Spatial Operations’ ribbon . . . . . . . . . . . . . . . . . . . . . . . . 540
H.23 Appearance of crop operation in the operations stack . . . . . . . . . . . . . 540
H.24 Performing an delete operation on a point cloud with a polygon using ‘Delete’
from the ‘Spatial Operations’ ribbon . . . . . . . . . . . . . . . . . . . . . . 541
H.25 Appearance of delete operation in the operations stack . . . . . . . . . . . . 541

T
H.26 Performing a set value operation (e.g. overwrite) on a point cloud with a poly-
gon using ‘Set Value’ from the ‘Spatial Operations’ ribbon . . . . . . . . . . . 542
H.27 Appearance of set value operation in the operations stack . . . . . . . . . . . 542
H.28 Import a nautical chart as a georeferenced tiff file . . . . . . . . . . . . . . . 543
H.29 Set the right map coordinate system for the geotiff . . . . . . . . . . . . . . 543
AF
H.30 Performing a contour operation on a nautical chart using lines to define the
contours and ‘Contour’ from the ‘Spatial Operations’ ribbon . . . . . . . . . . 543
H.31 Bring the sample set to the front if it appears behind the nautical chart . . . . 544
H.32 Appearance of contour operation in the operations stack . . . . . . . . . . . 544
H.33 Applying the copy to samples operation . . . . . . . . . . . . . . . . . . . . 544
H.34 Copy to samples operation result . . . . . . . . . . . . . . . . . . . . . . . 545
H.35 Applying the copy spatial data operation . . . . . . . . . . . . . . . . . . . 545
H.36 Copy spatial data operation result . . . . . . . . . . . . . . . . . . . . . . . 545
H.37 Activating the merge spatial data tool from the ribbon . . . . . . . . . . . . . 546
H.38 The merge operation requests a pointwise combination method . . . . . . . . 546
H.39 Resulting grid coverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
DR

H.40 Performing a gradient operation on a point cloud with a polygon using ‘Gradi-
ent’ from the ‘Spatial Operations’ ribbon . . . . . . . . . . . . . . . . . . . . 547
H.41 Appearance of gradient operation in the operations stack . . . . . . . . . . . 548
H.42 Interpolation Operation options . . . . . . . . . . . . . . . . . . . . . . . . 548
H.43 Averaging options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
H.44 Performing an interpolation operation on a single sample set (without using a
polygon) using ‘Interpolate’ from the ‘Spatial Operations’ ribbon . . . . . . . . 550
H.45 Appearance of interpolation of ‘set1’ to the coverage ’bed level’ in the opera-
tions stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
H.46 Performing an interpolation operation on multiple sample sets (without using a
polygon) using ‘Interpolate’ from the ‘Spatial Operations’ ribbon . . . . . . . . 551
H.47 Appearance of interpolation of ‘set1’ and ‘set2’ to the coverage ’bed level’ in
the operations stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
H.48 Performing a smoothing operation on a point cloud with a polygon using ‘Smooth-
ing’ from the ‘Spatial Operations’ ribbon . . . . . . . . . . . . . . . . . . . . 552
H.49 Appearance of smoothing operation in the operations stack . . . . . . . . . . 552
H.50 The cursor for the overwrite operation showing the value of the closest cover-
age point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
H.51 Performing an overwrite operation on a coverage point using ‘Single Value’
from the ‘Spatial Operations’ ribbon . . . . . . . . . . . . . . . . . . . . . . 554
H.52 Appearance of overwrite operation in the operations stack . . . . . . . . . . . 554
H.54 Input for the operation (top panel), mask for the operation (middle panel) and
output of the operation (bottom panel) . . . . . . . . . . . . . . . . . . . . . 555
H.53 The ‘Operations’ panel with the operations stack. In this example ‘bed level’
is the coverage (e.g. trunk) that is edited. The point clouds ‘set 1’ and ‘set 2’
(e.g. branches) are used to construct the ‘bed level’ coverage. . . . . . . . . 555
H.55 Editing the value or ‘Pointwise operation’ of a ‘Set Value’ operation using the
properties panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556

Deltares xxiii
 List of Figures

H.56 Disabling an operation using the boxed cross icon in the stack menu. The
operation will become grey. Note the exlamation marks marking the stack ‘out
of sync’. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557
H.57 Removing an operation from the stack using the cross icon in the stack menu . 557
H.58 Removing an operation from the stack using the context menu on the selected
operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
H.59 Refresh the stack using the ‘Refresh’ button so that all operation are (re-)
evaluated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
H.60 Quick link to the original dataset before performing any spatial operations . . . 559
H.61 Quick link to the output after performing all (enabled) operations . . . . . . . 559

T
AF
DR

Deltares xxiv
 1 A guide to this manual

1.1 Introduction
This User Manual describes the hydrodynamic module D-Flow Flexible Mesh (D-Flow FM)
which is part of the Delft3D Flexible Mesh Suite or D-HYDRO Suite. There are two different
releases for this suite; one for 1D2D modelling and one for 2D3D modelling. The current
document involves 2D3D modelling with D-Flow FM 2D3D, which is meant for coastal
seas, rivers and estuaries.

T
Note: D-Flow FM 1D2D and D-Flow FM 2D3D make use of different GUI’s, but use the same
computational kernel. Therefore, there are separate releases for 1D2D and 2D3D modelling.

This module is part of several Modelling suites, released by Deltares as Deltares Systems or
Dutch Delta Systems. These modelling suites are build with use of the Delta Shell framework.
AF The framework enables to develop a range of modeling suites, each distinguished by the
components and — most significantly — the (numerical) modules, which are plugged in. The
modules which are compliant with the Delta Shell framework are released as D-Name of the
module, for example: D-Flow Flexible Mesh, D-Waves, D-Water Quality, D-Real Time Control
and D-Rainfall Runoff.

Therefore, this User Manual is shipped with several modelling suites. On the Start Page
links are provided to all relevant User Manuals (and Technical Reference Manuals) for that
modelling suite. Other user manuals can be referenced. In that case, you need to open the
specific user manual from the Start Page in the central window. Some texts are shared in
different user manuals, in order to improve the readability.
DR

1.2 Overview
To make this manual more accessible we will briefly describe the contents of a lot of chapters
in this user manual.

If this is your first time to start working with D-Flow FM we suggest you to read Chapter 6, Get-
ting started with Graphical User Interface and carry out the tutorial exercises of Chapter 23.
These chapters explain the user interface and guide you through the modelling process re-
sulting in your first simulations with D-Flow FM.

Chapter 2: Introduction to D-Flow Flexible Mesh, provides specifications of D-Flow FM, such
as the areas of application, the standard and specific features provided, coupling to other
modules and utilities.

Chapter 3: Conceptual description of hydrodynamic equations, contains a description of the

conceptual model of D-Flow FM.

Chapter 4: Conceptual description of transport equation, discusses the modeled transport

processes, its conceptual model, boundary and initial conditions and user-relevant numerical
and physical settings of keywords.

Chapter 5: Conceptual description of heat flux models, provides a detailed insight into (the
modelling of) heat transport.

Chapter 6: Getting started with Graphical User Interface, gives an overview of the basic
features of the D-Flow FM GUI and will guide you through the main steps to set up a basic
D-Flow FM model.

Deltares 1 of 562
 A guide to this manual

Chapter 7: Set-up of a D-Flow FM model, provides practical information on the GUI, setting
up a model with all its parameters and tuning the model.

Chapter 8: Running a model, discusses how to validate and execute a model run. This can
either be done in the GUI, or in batch mode. The latter can also be done in combination with
parallel computing by using MPI. It also provides some information on run times and file sizes.

Chapter 9: Visualize results, explains in short the visualization of results within the GUI. It
introduces the program Delft3D-QUICKPLOT to visualize or animate the simulation results,
and Matlab for general post-processing.

T
Chapter 10: 3D modelling in D-Flow FM provides a detailed insight into the modelling of
stratified conditions for salinity, temperature, sediments, tracers or water quality substances.

Chapter 12: Hydraulic structures, gives background information of the available hydraulic
AF structures in D-Flow FM, the relevant definitions and the supported file formats.

Chapter 15: Wind, gives background information of how wind fields should be imposed, the
relevant definitions and the supported file formats.

Chapter 17: Coupling to external models via Basic Model Interface (BMI), provides guidance
on the integrated modelling of hydrodynamics (D-Flow FM) to external models.

Section 17.6: Coupling with D-Waves (SWAN), provides guidance on the integrated modelling
of hydrodynamics (D-Flow FM) and waves (D-Waves).
DR

Section 17.7: Coupling with D-RTC (FBC-Tools), provides guidance on the integrated mod-
elling of hydrodynamics (D-Flow FM) and real time control of hydraulic structures (D-RTC).

Section 17.8: Coupling with module for Sea Lock Exchange, provides guidance on the inte-
grated modelling of hydrodynamics (D-Flow FM) and ZSF (Sea Lock Exchange).

Chapter 18: Water quality and D-Flow FM, provides guidance on the integrated modelling of
hydrodynamics (D-Flow FM) and water quality (D-Water Quality).

Chapter 21: Calibration and data assimilation, describes how the OpenDA toolbox can be
deployed to apply calibration and/of data assimilation of D-Flow FM models.

Chapter 23: Tutorial, gives you hands-on experience in using the D-Flow FM GUI to define the
input of a simple problem, in validating this input, in executing the simulation and in inspecting
the results.

1.3 Typographical conventions

Throughout this manual, the following conventions help you to distinguish between different
elements of text.

Deltares 2 of 562
 A guide to this manual

Description
Example

Module Title of a window or a sub-window are in given in bold.

Project Sub-windows are displayed in the Module window and
cannot be moved.
Windows can be moved independently from the Mod-
ule window, such as the Visualisation Area window.

Save Item from a menu, title of a push button or the name of

T
a user interface input field.
Upon selecting this item (click or in some cases double
click with the left mouse button on it) a related action
will be executed; in most cases it will result in displaying
some other (sub-)window.
AF
<\tutorial\wave\swan-curvi>
In case of an input field you are supposed to enter input
data of the required format and in the required domain.

Directory names, filenames, and path names are ex-

<siu.mdw> pressed between angle brackets, <>. For Linux en-
vironments a forward slash (/) is used instead of the
backward slash (\) for Windows environments.

“27 08 1999” Data to be typed by you into the input fields are dis-
played between double quotes.
Selections of menu items, option boxes etc. are de-
scribed as such: for instance ‘select Save and go to
DR

the next window’.

delft3d-menu Commands to be typed by you are given in the font

Courier New, 10 points.

In this User manual, user actions are indicated with this

arrow.

[m s−1 ] [−] Units are given between square brackets when used
next to the formulae. Leaving them out might result
in misinterpretation. Most units will be in SI notation.
[m AD] stands for ’meter Above Datum’, which denotes
a level relative to the vertical reference system in the
model.

Command prompts and terminal output are shown in framed boxes with typewriter font:

> ./dflowfm --version

Deltares, D-Flow FM Version 1.1.149.41663, Sep 02 2015, 10:40:42
Compiled with support for:
IntGUI: no
OpenGL: no
OpenMP: yes
MPI : yes
PETSc : yes
METIS : yes

Deltares 3 of 562
 2 Introduction to D-Flow Flexible Mesh
D-Flow Flexible Mesh (D-Flow FM) is a hydrodynamic simulation program developed by Deltares.
It is the hydrodynamic module of Deltares’ unique, fully integrated computer software suite for
a multi-disciplinary approach with 1D, 2D and 3D modelling named Delft3D Flexible Mesh Suite
(abroad) or D-HYDRO Suite (in the Netherlands). 1D2D modelling is meant for urban, rural
and river applications, while 2D3D focusses on coastal seas, estuarines and rivers. It can
carry out simulations of hydrodynamic flows, water quality and ecology, waves and morphol-
ogy.

T
The term Flexible Mesh in the name refers to the flexible combination of unstructured grids
consisting of triangles, quadrangles, pentagons and hexagons.

It has been designed for experts and non-experts alike. The Delft3D Flexible Mesh Suite is
composed of several modules, grouped around a mutual interface, while being capable to
AF interact with one another. D-Flow FM, which this manual is about, is one of these modules.
D-Flow FM is a multi-dimensional (1D, 2D and 3D) hydrodynamic (and transport) simulation
program which calculates non-steady flow and transport phenomena that result from tidal and
meteorological forcing on unstructured, boundary fitted grids.

D-Flow Flexible Mesh can be coupled with the water quality module D-Water Quality. For the
interaction between waves and currents the flow module may be coupled with the short-waves
model D-Waves. To apply hydraulic structures in a model, D-Flow FM can be coupled to the
D-Real Time Control module.
DR

2.1 Applications
This section presents an overview of the domain of applicability of the model. This is done by
making claims about the types of practical and realistic situations in which the model can be
employed, and showing the nature and quality of the information that the model is capable of
generating in those situations.

The purpose of providing the reader with this inventory of application types is to allow the
reader to quickly recognise whether the model is indeed suitable for a particular application.
The computational model of D-Flow FM can be used in a wide range of applications, which
are listed below:

⋄ Tide and wind-driven flow (i.e., storm surges).

⋄ Density driven flow.
⋄ Horizontal transport of matter on large and small scales
⋄ Hydrodynamic impact of engineering works such as land reclamation, breakwaters, dikes
⋄ Hydrodynamic impact of hydraulic structures such as barriers, gates and weirs
⋄ Rainfall runoff in urban environments.
⋄ Simulation of tsunamis, hydraulic jumps, bores and flood waves.
⋄ Fresh-water river discharges in estuaries.
⋄ Spreading of waste water discharges from coastal outfalls
⋄ Thermal stratification in lakes, seas and reservoirs.
⋄ Impact of cooling water intakes and waste water outlets.
⋄ Sediment transport and morphodynamics via online coupling with hydrodynamics.
⋄ Water quality processes via online coupling with hydrodynamics.

Deltares 4 of 562
 Introduction to D-Flow Flexible Mesh

2.2 Modelling capabilities and advantages

⋄ Hydrodynamic modelling on unstructured grids, which offers extra flexibility of (grid) mod-
elling because triangles, quadrangles (four-sided), pentagons (five-sided) and hexagons
(six-sided) are possible.
⋄ A user-friendly and modern Grahical User Interface to set up a hydrodynamic model
⋄ Model input is independent of the grid (trachytopes excluded), so that changes to the grid
are easy and without much effort.
⋄ Possibility of parallel computing on MPI-based High Performance Computing clusters
⋄ In the vertical σ -layers and z -layers and z − σ -layers are possible, which offers huge
flexibility for vertical layer modelling.

T
⋄ Many options for hydraulic structures. Depending on the application the most suitable
approach can be selected.
⋄ High computational efficiency, leading to fast computation times
⋄ Coupling to external software via BMI-interfaces
⋄ Use of international standards, like outputting via NetCDF
AF
2.3 Current limitations for Delft3D Flexible Mesh Suite

2.3.1 General limitations

We start with limitations that are not related to either D-Flow FM, but are part of other modules
of the Delft3D Flexible Mesh Suite. This involves:
⋄ 1D, 2D and 3D modelling cannot be combined in the Delft3D Flexible Mesh Suite. Cur-
rently, only 1D and 2D can be combined into so-called 1D2D applications, by using D-
Flow FM 1D2D; see Deltares (2025b).
DR

⋄ The D-Particle Tracking module is currently either internal β -functionality (2D) or pre-α-
functionality (3D).
⋄ Nesting, which is a standard practice in automatic generation of boundary conditions from
a large to a small domain, isn’t available (cf. Delft3D-NESTHD module in Delft3D 4 Suite).
⋄ Wave modelling in 3D, via D-Waves, is α-functionality.
⋄ Morphology modelling in 3D, via D-Morphology, is α-functionality.

2.3.2 Limitations for D-Flow FM 2D3D

The following functionalities aren’t available in D-Flow FM 2D3D:
⋄ Coupling of 2D and 3D modelling isn’t possible.
⋄ Coupling of 1D and 3D modelling isn’t possible.
⋄ Bridge pillars aren’t possible in 3D.

Furthermore, the following functionalities are still β -functionality:

⋄ Long culverts
⋄ Sediment modelling in 3D
⋄ Self attraction and loading, which is required for tides in oceans.

(α-functionality: not feature complete)

(β -functionality: feature complete, to be used in projects, may contain showstoppers)
(General Availability: feature complete, fully validated, tested, well documented and sup-
ported)

Deltares 5 of 562
 Introduction to D-Flow Flexible Mesh

2.4 Coupling to other modules

The hydrodynamic conditions (velocities, water elevations, density, salinity, vertical eddy vis-
cosity and vertical eddy diffusivity) calculated in the D-Flow FM module are used as input to
the other modules of the Delft3D Flexible Mesh Suite, which are:

Module Description

D-Morphology cohesive and non-cohesive sediment transport

D-Real Time Control flow-triggered control of hydrodynamic structures

T
D-Water Quality (Delwaq) far-field water quality, see also chapter 18
D-Waves (SWAN) short wave propagation, see also section 17.6

For using D-Flow FM the following utilities are important:

AF Module Description

User Interface for complete model set-up and model runs, see chapter 6 and
chapter 7
RGFGRID for generating structured and unstructured grids
Delft3D-QUICKPLOT for visualisation and animation of simulation results
DFMOUTPUT
⋄ for merging partitioned map files into one, see sec-
DR

tion 8.4.4.
⋄ output of derived properties, such as the maximum value
of a time series, see section F.5.

For details on using these utility programs you are referred to the corresponding user manuals.

OpenEarthTools is an open source Toolbox consisting of MATLAB scripts for postprocessing

of D-Flow FM output files but this toolbox isn’t officially supported in combination with D-
Flow FM. For further information see http://www.openearth.eu.

2.5 Installation of D-Flow Flexible Mesh

D-Flow FM consists of a set of Computational Cores and a User Interface. The User Interface
is only available for Windows operating systems. The Computational Cores are available both
on Windows and Linux operating systems.

On Windows, D-Flow FM can be installed via a msi-file. Double-click it to start the installation
and follow the instructions. Both the Computational Cores and the User Interface will be
installed. Start the application from Start →All Programs →Deltares or by double-clicking
the short-cut on your desktop.

On Linux, the Computational Cores of D-Flow FM are available via an rpm-file or via an
Apptainer Container (previously known as Singularity). See the installation manual for more
details.

A Docker version is available upon request. Please contact Deltares if needed.

Deltares 6 of 562
 Introduction to D-Flow Flexible Mesh

2.6 Important differences compared to Delft3D-FLOW

The most noticeable difference between Delft3D-FLOW and D-Flow FM is the use of unstruc-
tured grids. Large regions with quadrangles can be coupled with much greater freedom than
before, using triangles, pentagons and hexagons. Grid refinement (and coarsening) without a
domain decomposition (DD) coupling is now possible in one and the same model grid. Finally,
many of Delft3D-FLOW’s grid restrictions are now gone: since there are no true grid ’rows’
and ’columns’ anymore, rows of grid cells may be coupled to columns, in any direction and at
any position. Furthermore, 1D networks can be coupled to 2D grids, either adjacent to each
other or the 1D network overlying the 2D grid. This is part of the D-Flow FM 1D2D suite.

T
In addition to the unstructured grid files, all geometric model input is now specified in geo-
graphical coordinates, either in Cartesian or spherical coordinates (x, y or longitude, latitude).
This is different from Delft3D-FLOW which required model input in (M,N) grid indices. This
so-called model-independent coordinates input allows for easy change of a model grid, while
AF with structured grids it can be time consuming to change the model grid.

The D-Flow FM Graphical User Interface provides a much more powerful and integrated envi-
ronment for setting up D-Flow FM models and inspecting model input such as time-dependent
forcings (boundary conditions and barrier control). Another improvement within the User In-
terface is the use of scripting for running and live interaction with a model.

D-Flow FM is coupled to the module for real time control of hydraulic structures (D-RTC),
which allows for much more possibilities compared to the real time control possibilities for
Delft3D-FLOW.
DR

Like Delft3D-FLOW, D-Flow FM implements a finite volume solver on a staggered grid. How-
ever, since there is no concept of grid ’rows’ and ’columns’, there is also no ADI-solver pos-
sible. The continuity equation is solved implicitly for all points in a single combined system.
Time integration is done explicitly for the advection terms in horizontal direction, and the re-
sulting dynamic time-step limitation is automatically set based on the Courant criterium. The
possible performance penalty that may result from this approach can often be remedied by
refining and coarsening the computational grid at the right locations. While Delft3D-FLOW in
practice never crashes, due to its more explicit time integration this might seldomly happen
with D-Flow FM, often in combination with D-Waves.

In D-Flow FM, the advection scheme is suitable for both sub-critical and critical flows. The
scheme is ’shock proof’ and is capable of reproducing correct bore propagation velocities.

In (De Goede, 2020), which contains a historical overview of 2D and 3D modelling of shallow
water flows in the Netherlands, the numerical approaches of both D-Flow FM and Delft3D-
FLOW have been described.

Deltares 7 of 562
 3 Conceptual description of hydrodynamic equations

3.1 Introduction
The hydrodynamic module D-Flow FM simulates one-dimensional (1D), two-dimensional (2DH,
depth-averaged) or three-dimensional (3D) unsteady flow and transport phenomena resulting
from tidal and/or meteorological forcing, including the effect of density differences due to a
non-uniform temperature and salinity distribution (density-driven flow). Also a combination of
1D and 2D modelling can be applied (1D2D). The hydrodynamic model is used to predict the
flow in shallow seas, coastal areas, estuaries, lagoons, rivers, lakes and polders. It aims to

T
model flow phenomena of which the horizontal length and time scales are significantly larger
than the vertical scales. The many applications that are possible with D-Flow FM, either with
D-Flow FM 1D2D or with D-Flow FM 2D3D have been summarized in section 2.1.

If the fluid is vertically homogeneous, a depth-averaged approach is appropriate. D-Flow FM

AF is able to run in two-dimensional mode (one computational layer), which corresponds to solv-
ing the depth-averaged equations. Examples in which the two-dimensional, depth-averaged
flow equations can be applied are tidal waves, storm surges, tsunamis, harbor oscillations
(seiches) and transport of pollutants in vertically well-mixed flow regimes.

One-dimensional modelling or 1D2D modelling with D-Flow FM 1D2D is available for urban,
rural and river and polder applications and sewer systems. Three-dimensional modelling with
D-Flow FM 2D3D is of particular interest in transport problems where the horizontal flow field
shows significant variation in the vertical direction. This variation may be generated by wind
forcing, bed stress, Coriolis force, bed topography or density differences. Examples are dis-
persion of waste or cooling water in lakes and coastal areas, upwelling and downwelling of
DR

nutrients, salt intrusion in estuaries, fresh water river discharges in bays and thermal stratifi-
cation in lakes and seas.

D-Flow FM is flexible by using an unstructured grid in the horizontal plane. In the vertical
direction D-Flow FM 2D3D offers two different vertical grid systems: a so-called σ co-ordinate
system (σ -model) introduced by Phillips (1957) for ocean models and the Cartesian z -co-
ordinate system (Z -model).

This section gives some background information on the conceptual model of the D-Flow FM
module. Most of the concepts and algorithms are applicable to both the σ -model and Z -
model.

3.2 Physical processes

The numerical hydrodynamic modelling system D-Flow FM solves the unsteady shallow water
equations in one (transverse and depth-averaged), two (depth-averaged) or in three (multi-
layer) dimensions. The system of equations consists of the horizontal equations of motion, the
continuity equation, and the transport equations for conservative constituents. The equations
are formulated in orthogonal Cartesian co-ordinates or in spherical co-ordinates on the globe.
In Cartesian co-ordinates, the free surface level and bathymetry are related to a flat horizontal
plane of reference, whereas in spherical co-ordinates the reference plane follows the Earth
curvature.

The flow is forced by among others tides, currents and discharges at the open boundaries,
wind stress at the free surface, pressure gradients due to free surface gradients (barotropic)
or density gradients (baroclinic). Source and sinks or laterals are included in the equations
to model the discharge and withdrawal of water and of constituents and substances, of which
the latter are subject to one or more water quality processes.

Deltares 8 of 562
 Conceptual description of hydrodynamic equations

The D-Flow FM model includes mathematical formulations that take into account the following
physical phenomena:

⋄ Propagation of long tidal waves (barotropic flow).

⋄ Horizontal density gradients via the pressure term (baroclinic effects).
⋄ Wind-driven flows; including space and time varying wind and atmospheric pressure, in-
cluding tropical cyclone winds.
⋄ Bed-stress including many options for vegetation.
⋄ The effect of the Earth rotation (via Coriolis force).
⋄ Heat exchange through the free water surface (via heat flux models).

T
⋄ Transport of dissolved material and pollutants (via transport equation).
⋄ Robust simulation of drying and flooding of inter-tidal flats and river winter beds.
⋄ Turbulence modelling (via turbulence closure models) (only 3D).
⋄ Transport of salt, heat and other conservative constituents.
⋄ Evaporation and precipitation.
⋄
AF ⋄
Tide generating forces.
Effect of secondary flow on depth-averaged momentum equations (for 3D effect in a 2D
model).
⋄ Influence of waves on the bed shear-stress (currently on for 2D).
⋄ Wave induced stresses (radiation stress)and mass fluxes (currently on for 2D).
⋄ Water quality processes in case of online coupling of hydrodynamics and water quality.
⋄ Sediment transport and morphodynamics via online coupling with hydrodynamics.

In case of 3D modelling advanced turbulence models to account for the vertical turbulent
viscosity and diffusivity are based on the eddy viscosity concept. Four closure models are
DR

provided in D-Flow FM:

1 constant,
2 algebraic,
3 k -ε and
4 k -τ model.

3.3 Hydrodynamic modelling

D-Flow FM solves the Navier Stokes equations for an incompressible fluid, under the shallow
water and the Boussinesq assumptions. In the vertical momentum equation the vertical ac-
celerations are neglected, which leads to the hydrostatic pressure equation. The set of partial
differential equations in combination with an appropriate set of initial and boundary conditions
is solved on an unstructured finite volume grid.

Two coordinate references are supported in D-Flow FM:

1 Cartesian co-ordinates
2 Spherical co-ordinates

For the sake of simplicity in this chapter the equations are only in Cartesian co-ordinates.

3.3.1 Model equations in 2D

In this section, we will present the governing equations in two horizontal directions, which
involves two momentum equations and the continuity equation.

Deltares 9 of 562
 Conceptual description of hydrodynamic equations

3.3.1.1 Momentum equations in horizontal direction (2D)

The momentum equations in x- and y -direction are given by:
 
∂U ∂U ∂U 1 ∂P ∂ ∂U
+U +V − fV = − + Fx + νV + Mx (3.1)
∂t ∂x ∂y ρ0 ∂x ∂z ∂z

 
∂V ∂V ∂V 1 ∂P ∂ ∂V
+U +V + fU = − + Fy + νV + My (3.2)
∂t ∂x ∂y ρ0 ∂y ∂z ∂z

T
Where U and V are the depth-averaged currents and νV is the vertical eddy viscosity coeffi-
cient. Density variations are neglected, except in the baroclinic pressure terms, ∂P/∂x and
∂P/∂y represent the pressure gradients.

The forces Fx and Fy in the momentum equations represent the unbalance of horizontal
AF Reynolds stresses.

Mx and My represent the contributions due to external sources or sinks of momentum (ex-
ternal forces by hydraulic structures, discharge or withdrawal of water, wave stresses, etc.).

The effects of surface waves on the flow as modelled in D-Flow FM are described in sec-
tion 3.8.

3.3.1.2 Continuity equation (2D)

DR

D-Flow FM solves the depth-averaged continuity equation, derived by integration the continu-
ity equation, for incompressible fluids (∇ • u = 0) over the total depth, taken into account the
kinematic boundary conditions at water surface and bed level, and is given by:

∂h ∂U h ∂V h
+ + =Q (3.3)
∂t ∂x ∂y
with U and V the depth averaged velocities. Q is representing the contributions per unit area
due to the discharge or withdrawal of water, precipitation and evaporation:
Z h
Q= (qin − qout ) dz + P − E (3.4)
0

with qin and qout the local sources and sinks of water per unit of volume [1/s], respectively, P
the non-local source term of precipitation and E non-local sink term due to evaporation. We
remark that the intake of, for example, a power plant is a withdrawal of water and should be
modelled as a sink. At the free surface there may be a source due to precipitation or a sink
due to evaporation.

3.3.2 Model equations in 3D

In this section, we will present the governing equations in two horizontal directions and one
vertical direction, which involves three momentum equations and the continuity equation.

3.3.2.1 Momentum equations in horizontal direction (3D)

The momentum equations in x- and y -direction are given by:
 
∂u ∂u ∂u ∂u 1 ∂P ∂ ∂u
+u +v +w − fv = − + Fx + νV + Mx (3.5)
∂t ∂x ∂y ∂z ρ0 ∂x ∂z ∂z

Deltares 10 of 562
 Conceptual description of hydrodynamic equations

 
∂v ∂v ∂v ∂v 1 ∂P ∂ ∂v
+u +v +w + fu = − + Fy + νV + My (3.6)
∂t ∂x ∂y ∂z ρ0 ∂y ∂z ∂z
Where νV is the vertical eddy viscosity coefficient. Density variations are neglected, except
in the baroclinic pressure terms, ∂P/∂x and ∂P/∂y represent the pressure gradients.

The forces Fx and Fy in the momentum equations represent the unbalance of horizontal
Reynolds stresses.

T
Mx and My represent the contributions due to external sources or sinks of momentum (ex-
ternal forces by hydraulic structures, discharge or withdrawal of water, wave stresses, etc.).

The effects of surface waves on the flow as modelled in D-Flow FM are described in sec-
AF
3.3.2.2
tion 3.8.

Vertical velocities (3D)

The vertical velocity w in the adapting σ co-ordinate system is computed from the continuity
equation:

∂h ∂uh ∂vh ∂w
+ + + = h (qin − qout ) (3.7)
∂t ∂x ∂y ∂z
At the surface the effect of precipitation and evaporation is taken into account. The vertical
velocity w is defined at the σ -surfaces. w is the vertical velocity relative to the moving σ -plane.
DR

It may be interpreted as the velocity associated with up- or downwelling motions.

3.3.3 The hydrostatic pressure assumption

Under the shallow water assumption, the vertical momentum equation is reduced to a hydro-
static pressure equation. Vertical accelerations due to buoyancy effects and due to sudden
variations in the bed topography are not taken into account. So:

∂P
= −ρg (3.8)
∂z
For water of constant density and taking into account the atmospheric pressure, it includes
gradients of the free surface level, called barotropic pressure gradients. The atmospheric
pressure is included in the system for storm surge simulations. The atmospheric pressure
gradients dominate the external forcing at peak winds during storm events. Space and time
varying wind and pressure fields are especially important when simulating storm surges.

In case of a non-uniform density the pressure gradients includes not only barotropic pressure
gradient, but also vertical pressure gradient, the so called baroclinic pressure gradient. The
baroclinic pressure gradient is the result of variable distribution of density and temperature in
the vertical direction.

In the horizontal gradient a vertical derivative is introduced by the σ co-ordinate transforma-

tion. In estuaries and coastal seas the vertical grid may deteriorate strongly in case of steep
bed slopes. In order to avoid artificial flow the numerical approximation of the baroclinic pres-
sure terms requires a special numerical approach. The treatment of D-Flow FM to avoid the
artificial mixing due to σ co-ordinates are discussed in section 22.7, see also Stelling and Van
Kester (1994).

Deltares 11 of 562
 Conceptual description of hydrodynamic equations

3.3.4 The Coriolis force

The Coriolis parameter f depends on the geographic latitude ϕ and the angular speed of
rotation of the earth, Ω (f = 2Ω sin ϕ). For a grid the user should specify the space varying
Coriolis parameter, using a suitable projection. This can be done by selecting Coordinate
System in RGFGRID, and selection of the option for Spherical Coordinate. The parameters
for translation and rotation can be given as shown in Figure 3.1.

T
AF
Figure 3.1: Input for map projection for specifying Coriolis parameter on the grid.

3.3.5 Diffusion of momentum

The forces Fx and Fy in the horizontal momentum equations represent the unbalance of
horizontal Reynolds stresses. The Reynolds stresses are modelled using the eddy viscosity
DR

concept, (for details e.g. Rodi (1984)). This concept expresses the Reynolds stress compo-
nent as the product between a flow as well as grid-dependent eddy viscosity coefficient and
the corresponding components of the mean rate-of-deformation tensor. The meaning and the
order of the eddy viscosity coefficients differ for 2D and 3D, for different horizontal and vertical
turbulence length scales and fine or coarse grids. In general the eddy viscosity is a function
of space and time.

For 3D shallow water flow the stress tensor is an-isotropic. The horizontal eddy viscosity
coefficient, νH , is much larger than the vertical eddy viscosity νV (νH ≫ νV ). The horizontal
viscosity coefficient may be a superposition of three parts:

1 a part due to "sub-grid scale turbulence",

2 a part due to "3D-turbulence" see Uittenbogaard et al. (1992) and
3 a part due to dispersion for depth-averaged simulations.

In simulations with the depth-averaged momentum and transport equations, the redistribution
of momentum and matter due to the vertical variation of the horizontal velocity is denoted
as dispersion. In 2D simulations this dispersion is not simulated as the vertical profile of the
horizontal velocity is not resolved. Then this dispersive effect may be modelled as the product
of a viscosity coefficient and a velocity gradient. The dispersion term may be estimated by the
Elder formulation.

If the vertical profile of the horizontal velocity is not close to a logarithmic profile (e.g. due to
stratification or due to forcing by wind) then a 3D-model for the transport of matter is recom-
mended.

The horizontal eddy viscosity is mostly associated with the contribution of horizontal turbulent
motions and forcing that are not resolved by the horizontal grid ("sub-grid scale turbulence") or

Deltares 12 of 562
 Conceptual description of hydrodynamic equations

by (a priori) the Reynolds-averaged shallow-water equations. in 3D, in the vertical direction,

νV is referred to as the three-dimensional turbulence and in it is computed following a 3D-
turbulence closure model.

Therefore, in addition to all turbulence closure models in D-Flow FM a constant (space and
time) background mixing coefficient may be specified by the user, which is a background
value for the vertical eddy viscosity in the momentum Equation (3.5) and Equation (3.6) con-
sequently.

The horizontal and vertical eddy viscosities can be set by user defined value under Physical

T
Parameters shown in Figure 3.2.

AF
DR

Figure 3.2: Input parameters for horizontal and vertical eddy viscosities.

The default approach for the computation of the horizontal viscosity in D-Flow FM is the so-
called Smagorinsky approach, which results into time and space varying horizontal viscosity
coefficients. Due to the explicit time integration of the horizontal viscosity term a time step
criterion is applied in order to ensure stable model results. If this criterion is violated, then the
horizontal viscosity coefficient at a certain flow link is reduced. Next, in the diagnostic file a
warning is generated as shown below.

** WARNING: Viscosity coefficient was limited for 3309 links.

** WARNING: Viscosity coefficient was limited for 3269 links.
** WARNING: Viscosity coefficient was limited for 3411 links.

Per time step is shown in how many flow links the horizontal viscosity coefficient has been
reduced. After ten warnings this message is stopped, in order to prevent that the diagnostic
file will become very large. The following message is written in the diagnostic file at the end
of the simulation:

** INFO : Viscosity coefficient/Horizontal transport flux were limited on some links in the course of computation.

3.3.6 Bed friction

The boundary conditions for the momentum equations 3.5 and 3.6 at the bed (z = zb ) are:

νV ∂u 1
= τbx (3.9)
H ∂σ σ=0 ρ0

Deltares 13 of 562
 Conceptual description of hydrodynamic equations

and

νV ∂v 1
= τby (3.10)
H ∂σ σ=0 ρ0
with τbx and τby the components of the bed stress in x- and y -direction, respectively. These
equations hold in 2D and 3D parts of the model, in 1D modelling the equation reduces to a
single component along the channel.

Depth-averaged flow

T
For 2D depth-averaged flow the shear-stress at the bed induced by a turbulent flow is assumed
to be given by a quadratic friction law:

ρ0 gU |U |
τb = , (3.11)
AF 2
C2D

where |U | is the magnitude of the depth-averaged horizontal velocity. In D-Flow FM we

support the following equations to compute the C2D coefficient. The numbers and strings
following the name of the roughness formulation indicate the number and name by which the
formulations are selected in the input files.
⋄ Chézy formulation: 0, Chezy

C2D = Chézy coefficient [m1/2 /s]. (3.12)

⋄ Manning’s formulation: 1, Manning

DR

As formulated by Manning (1891), and also known as Gauckler-Manning-Strickler formu-

lation.
√
6
R
C2D = (3.13)
n
where:
R is the hydraulic radius
n is the Manning coefficient [m−1/3 s].
⋄ Log law of the Wall: 2, WallLawNikuradse
√  
g 30R
C2D = ln (3.14)
κ ekn
where:
R is the hydraulic radius
kn is the Nikuradse roughness length [m].
⋄ White-Colebrook’s formulation: 3, WhiteColebrook
As formulated by Colebrook and White (1937) and Colebrook (1939).
 
10 12R
C2D = 18 log (3.15)
kn
where:
R is the hydraulic radius
kn is the Nikuradse roughness length [m].

Deltares 14 of 562
 Conceptual description of hydrodynamic equations

Alluvial bed properties and land use data can be used to determine the roughness and flow
resistance. Specific functionality has been implemented to make the translation of bed and
land use properties into roughness and flow resistance characteristics. See section 13.2 for
details.

Three-dimensional flow
For 3D models, a quadratic bed stress formulation is used that is quite similar to the one for
depth-averaged simulations. The bed shear stress in 3D is related to the current just above
the bed:

T
gρ0 ub |ub |
τ b3D = 2
, (3.16)
C3D

with |ub | the magnitude of the horizontal velocity in the first layer just above the bed. The con-
AF tribution of the vertical velocity component to the magnitude of the velocity vector is neglected.
The log-law wall function for a rough bed reads
 
u∗ z + µz0
ub = ln , (3.17)
κ z0
where z0 is the roughness height and µ is a constant that is set to 9 in D-Flow FM. The first
grid point above the bed is assumed to be situated in the logarithmic boundary layer. Let ∆zb
be the distance to the computational grid point closest to the bed. Then, by integrating of the
first layer above the bed we arrive at
DR

 
u∗ ∆zb + µz0
ub = ln , (3.18)
κ ez0
The magnitude of the bottom stress is defined as:

|τ b | = ρ0 u∗ |u∗ | . (3.19)

Using Eqs. 3.16 to 3.19, C3D can be expressed in the roughness height z0 of the bed:
√  
g ∆zb + µz0
C3D = ln . (3.20)
κ ez0

3.3.7 Roughness definition input

The roughness definition (or: friction values) can be done in two ways:
⋄ 2D grid parts may use a global friction value, specified in the MDU file (Appendix A) under
[physics], keyword UnifFrictCoef. Note that the available UnifFrictType
values are limited to 0, 1, 2, 3.
⋄ Alternatively, 2D grid parts may have spatially varying friction values defined via the pa-
rameter field file, specified in the MDU file under [geometry], keyword IniFieldFile.
The spatially varying friction values have to be provided in a separate data file, and
interpolation of that data onto the 2D grid is controlled by several parameters in the
IniFieldFile. All details are given in section D.2.

Deltares 15 of 562
 Conceptual description of hydrodynamic equations

3.4 Equations of state for the density

The density of water ρ is a function of salinity (s) and temperature (t).

In D-Flow FM we copied the implementation from Delft3D-FLOW of the formulation derived

by Eckart (1958) that is based on a limited number of measurements dating from 1910 (only
two salinities at 5 temperatures). In the original equation the pressure is present, but at low
pressures the effect on density can be neglected.

Eckart formulation

T
The Eckart formulation is given by (Eckart, 1958):

Range: 0 < T < 40 ◦ C, 0 < s < 40 ppt

1 000P0
AF where:
ρ=
λ + α 0 P0
, (3.21)

λ = 1 779.5 + 11.25T − 0.074 5T 2 − (3.80 + 0.01T ) s, (3.22)

α0 = 0.698 0, (3.23)
P0 = 5 890 + 38T − 0.375T 2 + 3s. (3.24)

with the salinity s in [ppt] and the water temperature T in [◦ C].

DR

The keyword that selects the equation of state in the mdu file is called Idensform. The influ-
ence of salinity and or temperature on water motion through the baroclinic pressure can be
switched off by setting Idensform=0

UNESCO formulation
The UNESCO formulation is given by (UNESCO, 1981a):

Range: 0 < T < 40 ◦ C, 0.5 < s < 43 ppt

ρ = ρ0 + As + Bs3/2 + Cs2 (3.25)

where

ρ0 = 999.842 594 + 6.793 952 × 10−2 T − 9.095 290 × 10−3 T 2 +

+ 1.001 685 × 10−4 T 3 − 1.120 083 × 10−6 T 4 + 6.536 332 × 10−9 T 5
(3.26)
−1 −3 −5 2
A = 8.244 93 × 10 − 4.089 9 × 10 T + 7.643 8 × 10 T +
− 8.246 7 × 10−7 T 3 + 5.387 5 × 10−9 T 4 (3.27)
B = −5.724 66 × 10−3 + 1.022 7 × 10−4 T − 1.654 6 × 10−6 T 2 (3.28)
C = 4.831 4 × 10−4 (3.29)

with the salinity s in [ppt] and the water temperature T in [◦ C].

Note: The UNESCO formulation is set as default.

Remarks:

Deltares 16 of 562
 Conceptual description of hydrodynamic equations

⋄ Equation (3.27) is known as the International Equation of State for Seawater (EOS80)
and is based on 467 data points. The standard error of the equation is 3.6 × 10−3
kg/m3 (Millero and Poisson, 1981).
⋄ The Practical Salinity Scale (UNESCO, 1981b, Par. 3.2) and the International Equation
of State are meant for use in all oceanic waters. However, these equations should be
used with caution in waters that have a chemical composition different from standard
seawater. In such waters, densities derived with the methods based on practical salinity
measurements and the International Equation of State may deviate measurably from
the true densities. However, in water masses different in composition from standard
seawater the differences in densities derived by the new equations involve only very

T
small errors.

Recommendation
The UNESCO formulae serve as an international standard. Further, the UNESCO formulae
AF show the correct temperature of 4 degrees Celsius where fresh water has its maximum den-
sity. The latter is of importance for thermal stratification in deep lakes in moderate climate
zones. Therefore we recommend the application of the UNESCO formulae and to select the
Eckart formulation only for consistence with previous projects in which it has been used. At
this moment the default is UNESCO.

Nevertheless, the UNESCO formulae have their limitations as they are based on the general
properties of seawater mixed with fresh water. Particularly in cases where marginal density
differences play a role, typically lakes, a variable mineral content of the water may create den-
sity differences not detected by just temperature and salinity. For such dedicated cases, you
are warranted to check the accuracy of the UNESCO formulae against experimental density-
DR

relations derived from the (lake) water. In case of deviations or other constituents determining
the water density, we then recommend to contact the Helpdesk for further assistance such as
the implementation of a more dedicated density formulation.

3.5 Shear-stresses at closed boundaries

A closed boundary is situated at the transition between land and water. At a closed boundary,
two boundary conditions have to be prescribed. One boundary condition has to do with the
flow normal to the boundary and the other one with the shear-stress along the boundary.
A closed sidewalls is always considered as impermeable. For the shear stress along the
boundary, the possible conditions to be prescribed are free-slip (zero tangential shear-stress),
partial-slip and full-slip.

For large-scale simulations, the influence of the shear-stresses along closed boundaries can
be neglected. Free slip is then applied for all closed boundaries. For simulations of smallscale
flow (e.g. laboratory scale), the influence of the side walls on the flow may no longer be
neglected. This option has been implemented for closed boundaries and dry points but not for
thin dams. The reason is that the shear stress at a thin dam is dependent on the side (double
valued).

Along the side walls, the tangential shear stress is calculated based on a logarithmic law of
the wal. The friction velocity u∗ is determined by the logarithmic law for a rough wall, with side
wall roughness y0 and the velocity in the first grid point near the side wall. Let ∆ys be the
grid size normal to the sidwall, then:
 
→ u∗ ∆ys
| u sidewall | = ln 1 + (3.30)
κ 2y0

Deltares 17 of 562
 Conceptual description of hydrodynamic equations

The choice for the way tangial shear stress are computed can be inserted through the key
irov in the MDU-file (under [physics]):
⋄ the case irov = 0 treats the side walls as free-slip walls (default),
⋄ the case irov = 1 treats the side walls as partial-slip walls,
⋄ the case irov = 2 treats the side walls as no-slip walls.

If the choice for partial-slip walls is made, then a specific wall roughness value should be pre-
scribed in the MDU-file. For this, the keyword wall_ks should be used (under [physics]
in the MDU-file). The computational engine interpretes this value as Nikuradse roughness ks .

T
The value for y0 is computed as y0 = ks /30.

3.6 Secondary flow

The flow in a river bend is basically three-dimensional. The velocity has a component in the
AF plane perpendicular to the river axis. This component is directed to the inner bend near the
riverbed and directed to the outer bend near the water surface, see Figure 3.3.

u
v

+s τbs
DR

τb δ

τbn
+r

Figure 3.3: Vertical profile secondary flow (v ) in river bend and direction bed stress

This so-called "secondary flow" (spiral motion) is of importance for the calculation of changes
of the riverbed in morphological models and the dispersion of matter. It strongly varies over the
vertical but its magnitude is small compared to the characteristic horizontal flow velocity. In a
3D model the secondary flow is resolved on the vertical grid, but in 2D depth-averaged model
the secondary flow cannot be simulated in this way, because a vertical component doesn’t
exist. Therefore, it can be be simulated in a simplified way by using a so-called secondary
flow model. In this section the secondary flow model in D-Flow FM is described.

3.6.1 Definition
The secondary flow will be defined here as the velocity component v (σ) normal to the depth-
averaged main flow. The spiral motion intensity of the secondary flow I is a measure for the
magnitude of this velocity component along the vertical:
Z 1
I= |v (σ)| dσ (3.31)
0

Deltares 18 of 562
 Conceptual description of hydrodynamic equations

A vertical distribution for a river bend is given in Figure 3.3. The spiral motion intensity I leads
to a deviation of the direction of the bed shear stress from the direction of the depth-averaged
flow and thus affects the bedload transport direction. This effect can be taken into account in
morphological simulations.

The component of the bed shear stress normal to the depth-averaged flow direction τbr reads:

 α
τbr = −2ρα2 1 − |u| I (3.32)
2

T
where α is defined in Equation (3.42) and |u| is the magnitude of the depth-averaged velocity.
To take into account the effect of the secondary flow on the depth-averaged flow, the depth-
averaged shallow water equations have to be extended with:
⋄ An additional advection-diffusion equation to account for the generation and adaptation of
the spiral motion intensity.
AF ⋄ Additional terms in the momentum equations to account for the horizontal effective shear
stresses originating from the secondary flow.

3.6.2 Momentum equations in horizontal direction

When applying a secondary flow model, this does not lead to any conceptual changes in
the continuity equation. Therefore, equation 3.3 is still relevant. However, the momentum
equations in x- and y -direction will be extended with and extra term, which is given by:
√
∂U ∂U ∂U 1 ∂P gu u2 + v 2
+U +V − fV = − − + Fx + Fsx + Mx (3.33)
DR

2
∂t ∂x ∂y ρ0 ∂x C2D h
√
∂V ∂V ∂V 1 ∂P gv u2 + v 2
+U +V + fU = − − 2
+ Fy + Fsy + My (3.34)
∂t ∂x ∂y ρ0 ∂y C2D h
The fourth term in the right-hand side represents the effect of the secondary flow on the depth-
averaged velocities (shear stresses by depth-averaging the non-linear acceleration terms).

3.6.3 Effect of secondary flow on depth-averaged momentum equations

To account for the effect of the secondary flow on the depth-averaged flow, the momentum
equations have to be extended with additional shear stresses. To close the equations these
stresses are coupled to parameters of the depth-averaged flow field. The main flow is as-
sumed to have a logarithmic velocity profile and the secondary flow originates from a multipli-
cation of a universal function with the spiral motion intensity, see Kalkwijk and Booij (1986).
Depth averaging of the 3D equations leads to correction terms in the depth-averaged momen-
tum equations for the effect of spiral motion:
 
1 ∂hTxx ∂hTxy
Fsx = + (3.35)
h ∂x ∂y
 
1 ∂hTxy ∂hTyy
Fsy = + (3.36)
h ∂x ∂y
with the shear-stresses, resulting from the secondary flow, modelled as:

Txx = −2βuv (3.37)

Txy = Tyx = β(u2 − v 2 ) (3.38)
Tyy = 2βuv (3.39)

Deltares 19 of 562
 Conceptual description of hydrodynamic equations

and:
h
β = β∗ (3.40)
Rs∗
∗
β = βc 5α − 15.6α2 + 37.5α3


(3.41)

βc ∈ [0, 1], correction coefficient specified by you,

√
g 1
α= < (3.42)
κC2D 2

T
with Rs∗ the effective radius of curvature of a 2D streamline to be derived from the intensity of
the spiral motion and κ the Von Kármán constant. The spiral motion intensity is computed by
Equation (3.43). The limitation on α, Equation (3.42), is set to ensure that the length scale La
in Equation (3.50) is always positive. For βc = 0, the depth-averaged flow is not influenced
AF by the secondary flow.

Remark:
⋄ Equation (3.42) effectively means a lower limit on C2D .

3.6.4 The depth averaged transport equation for the spiral motion intensity
The variation of the spiral motion intensity I in space and time, is described by a depth-
averaged advection-diffusion equation:
   
DR

∂hI ∂U hI ∂V hI ∂ ∂I ∂ ∂I
+ + =h DH +h DH + hS (3.43)
∂t ∂x ∂y ∂x ∂x ∂y ∂y
with:
I − Ie
S=− (3.44)
Ta
Ie = Ibe − Ice (3.45)
h
Ibe = |U | (3.46)
Rs
h
Ice = f (3.47)
√2
|U | = U 2 + V 2 (3.48)
La
Ta = (3.49)
|U |
(1 − 2α) h
La = (3.50)
2κ2 α
and Rs the radius of curvature of the stream-line defined by:

Us ∂Ur
=− (3.51)
Rs ∂s
with Us and Ur the components along and perpendicular to the streamline. The effective
radius of curvature to be used for the evaluation of the coefficient β , Equation (3.41), reads:

h |U |
Rs∗ = (3.52)
I

Deltares 20 of 562
 Conceptual description of hydrodynamic equations

To guarantee stability the effective radius of curvature is bounded by the following empirical
relation:

Rs∗ ≥ 10h (3.53)

The above formulas account for two sources of secondary flow:

⋄ The centrifugal force in case of curved streamlines, Ibe .
⋄ The effect of the Coriolis force, Ice .

T
3.7 Tide generating forces
Numerical models of tidal motion in coastal seas generally do not account for the direct local
influence of the tide generating forces. The amount of water mass in these models is relatively
small and the effect of these forces on the flow can be neglected. In that case, tidal motion
can often be reproduced with sufficient accuracy just by prescribing the tidal forcing along
AF open model boundaries.

In models covering larger seas or oceans, the contribution of the gravitational forces on the
water motion increases considerably and can no longer be neglected. In a global model,
open boundaries are absent and the tidal motion can only be induced by including tide gen-
erating forces. Because tidal forces only play a significant role in the larger models, and
because the exact position of each computational point on earth must be known, we have
implemented these forces only in combination with spherical coordinates. By default, tide
generating forces is switched on in spherical models. You can switch it off by setting in the
mdu file: Tidalforcing = 0
DR

The tide generating forces originate from the Newtonian gravitational forces of the terrestrial
system (Sun, Moon and Earth) on the water mass. The equilibrium tide is the tide that would
result from the gravitational forces if a solid earth would be completely covered by an ocean
of about 21.5 km deep, such that the wave propagation speed would match the speed of the
celestial forces over the ocean surface. The interacting frequencies that result can be grouped
as diurnal, semi diurnal and long periodic. The total number of tide generating frequencies that
is evaluated in the computation is a tradeoff between required accuracy and computational
cost. Per default, we use a set of 60 frequencies.

A smaller set of 11 main frequencies as used in Delft3D-FLOW can also be selected by setting
in the MDU file :

Doodsonstart = 57.555
Doodsonstop = 275.555
Doodsoneps = 0.030

The full set of 484 components can be selected by specifying:

Doodsonstart = 55.565
Doodsonstop = 375.575
Doodsoneps = 0.000

For the set of 60 components these numbers are:

Deltares 21 of 562
 Conceptual description of hydrodynamic equations

Doodsonstart = 55.565
Doodsonstop = 375.575
Doodsoneps = 0.030

The earth itself is deformed by the celestial forces, this is called the solid earth tide. An
estimate of this influence is based on the work of Love (1927), is included in the total tide
generating potential.

T
Details on the implementation of tide generating forces can be found in the lecture notes of
Schrama (2007).

In order to save computation cost, the tidal potential is not computed for each computational
point, but on a grid with a resolution of 1 degree in both the South-North and West-East
AF direction.

The tidal and surge motions of the seas and ocean also deform the earth, which is called tidal
loading. Next to that, the water at some point is attracted by all moving water elsewhere on
the globe. This is called self attraction. The combined influence of self attraction and loading
is beta functionality.

3.8 Wave forcing in D-Flow FM

In relatively shallow areas (coastal seas) wave action becomes important because of several
processes:
DR

⋄ In the surf zone long-shore currents and a cross-shore set-up is generated due to varia-
tions in the wave-induced momentum flux (radiation stress). In case of an irregular surf
zone, bathymetry strong circulations may be generated (rip currents).
⋄ The bed shear stress is enhanced; this affects the stirring up of sediments and increases
the bed friction.

These processes are accounted for in a wave-averaged manner. Some processes basically
act at a specific location or interface, such as the enhanced bed shear-stress or wave breaking
at the surface, while others have a (certain) distribution over the vertical, such as the energy
dissipation due to bottom friction in the wave boundary layer.

The computation of waves and wave-induced effects is the domain of wave models. D-Waves
supports currently one wave model: SWAN, a third generation wave model (Ris, 1997). SWAN
computes the full (directional and frequency) spectrum on a rectilinear or curvilinear grid with
many processes formulated in detail. For details and background you are referred to the
D-Waves User Manual (Deltares, 2025j) and the references cited above.

For the sake of simplicity, we will describe in this section all wave-induced effects on a rect-
angular grid. In D-Flow FM, however, these terms have been implemented in an unstructured
co-ordinate system. For a full wave-current interaction the currents from D-Flow FM are used
in D-Waves (current refraction). The numerical grids used in the flow and wave computation
often differ. SWAN works on a rectilinear or curvilinear grid, while D-Flow FM only works with
unstructured grids. Unstructured SWAN is not yet supported. To use the required grid reso-
lution in the area of interest you can use nested grids. The transformation of results between
the nested grids and the grids used in the flow and in the wave computations is executed au-
tomatically and is fully transparent to you. The general procedure to derive the wave-induced
forces is:

Deltares 22 of 562
 Conceptual description of hydrodynamic equations

⋄ Average the continuity equation and the momentum equations over the wave period.
⋄ Express the residual terms that remain compared to the case without waves in terms of
the wave properties, such as the wave energy, the phase and group velocity, and wave
length or wave period.

Obviously, there are various averaging procedures. A straightforward approach is to define the
mean motion by time averaging the equations over a wave period. The momentum equation in
x-direction, averaged over the wave motion and expressed in Cartesian co-ordinates is given
by:

T
∂ ūj ∂ ūj ∂ ζ̄ 1 ∂ τ̄ij
+ ūi + ... + g − = Fj , (3.54)
∂t ∂xj ∂xj ρ ∂xi
where for i and j the summation rule applies, i, j = {1, 2, 3}, the wave averaged quantity is
indicated by an overhead bar, ūj is the wave-mean velocity component, ζ̄ is the wave-mean
AF
free surface elevation, τ̄ij are the components of the wave-averaged normal stress tensor,
and Fj is the wave-induced force that remains after averaging the momentum equation over
the wave period. This wave induced force can generally be written as the gradient of the
radiation-stress tensor S :
∂Sij
Fi = − . (3.55)
∂xj

Using wave propagation models we can express Sij in terms of the wave parameters, such
as the wave energy, the phase and group velocity, the wave length and the wave period. The
DR

wave-induced force is computed as the gradient of the radiation stress terms.

The above given procedure can only be applied when the mean motion is uniform with depth.
In most practical cases this does not apply. Then the only way to split the mean and oscillating
motion is through the Generalised Lagrangian Mean, GLM method of Andrews and McIntyre
(1978). As shown by Andrews and McIntyre (1978), Groeneweg and Klopman (1998) and
Groeneweg (1999) the (depth averaged and 3D) flow equations written in a co-ordinate sys-
tem moving with the Stokes drift are very similar to the ordinary Eulerian formulation. However,
the wave-induced driving force due to averaging over the wave motion is more accurately ex-
pressed in wave properties. The relation between the GLM velocity and the Eulerian velocity
is given by:

uL = uE + uS , (3.56)

where uL is the GLM-velocity vector, uE is the ordinary Eulerian-velocity vector and uS is

the Stokes-drift vector.

The momentum equation in x-direction, averaged over the wave motion and expressed in
GLM co-ordinates is given by:

∂ ūLj ∂ ūLj ∂ ζ̄ 1 ∂ τ̄ijL

+ ūLi + ... + g − = FjL , (3.57)
∂t ∂xj ∂xj ρ ∂xi

where for i and j the summation rule applies, i, j = {1, 2, 3}, and the quantities have the
same meaning as in Equation (3.54), but now in GLM co-ordinates. As shown by Groeneweg
(1999) the right-hand side of Equation (3.57) contains a term related to a Stokes correction of
the shear stresses. In the current implementation this term is neglected.

So in short:

Deltares 23 of 562
 Conceptual description of hydrodynamic equations

⋄ In D-Flow FM, the hydrodynamic equations are written and solved in GLM-formulation,
including the wave-current interactions.
⋄ The GLM velocities are written to the communication file and are used in all transport
computations. Quantities moving with the flow are transported by the total, i.e. the GLM,
velocity and not the Eulerian velocity.
⋄ The Eulerian velocities are written to the D-Flow FM result files to be used in comparisons
of computational results with measurements if [output] EulerVelocities in the
MDU-file is set to 1.
⋄ The only difference in the computational procedure as compared to the ordinary Eulerian
formulation occurs at the boundaries. The velocity at the bottom is not the total velocity but

T
the Eulerian velocity; so the bed-shear-stress is corrected for the Stokes drift. At lateral
velocity boundaries, the total velocity must be prescribed; the implementation is such that
the Eulerian velocity is prescribed in the boundary conditions (by you) and the Stokes drift
is added by D-Flow FM. At water level boundaries, just the wave-mean water level must
be prescribed.
AF In the following sections, we discuss the wave-current interaction terms and their possible
profile in the vertical. Where applicable we distinguish between the depth-averaged and the
3D formulations.

Remarks:
⋄ For brevity, we suppress the index L for GLM quantities. So, in this section a velocity
without super-script refers to the GLM velocity, unless explicitly mentioned differently.
⋄ A super-script S is used to indicate the Stokes drift.
DR

3.8.1 Forcing by radiation stress gradients

The wave-induced force, i.e. the right-hand side of Equation (3.57), can be expressed in the
wave parameters of the wave model that is being applied. For linear current refraction the
expression can be derived analytically. To account for wave dissipation due to for instance
bottom friction, wave breaking and whitecapping and wave growth due to wind one can rely
on mild slope formulations with dissipation terms.

As shown by Dingemans et al. (1987), using the gradients of the radiation stresses in numer-
ical models can result in spurious currents. Dingemans et al. (1987) showed that the diver-
gence free part of the radiation stress is not capable of driving currents and can therefore
be neglected if one is primarily interested in wave-driven currents. The remaining part of the
radiation stress gradients is closely related to the wave energy dissipation, i.e. the right-hand
side of Equation (3.57) can be written as:
Dki
Fi = , (3.58)
ω
where D is the total energy dissipation due to waves, ki is the wave number in i-direction
and ω is the wave frequency; see Dingemans (1997) for many details and discussions on this
subject.

For a depth averaged model the momentum equations in x- and y -direction, leaving out most
of the terms, can be written as:
√
∂U gU U 2 + V 2
+ ... + 2
+ . . . = . . . + Fx , (3.59)
∂t C2D (d + ζ)
√
∂V gV U 2 + V 2
+ ... + 2
+ . . . = . . . + Fy , (3.60)
∂t C2D (d + ζ)

Deltares 24 of 562
 Conceptual description of hydrodynamic equations

where Fx and Fy are the depth averaged wave-induced forcings and given by the gradients
of the radiation stress tensor S , or following Dingemans et al. (1987) approximated by wave
energy dissipation:

∂Sxx ∂Syx kx
Fx = − − =D , (3.61)
∂x ∂y ω

∂Sxy ∂Syy ky
Fy = − − =D . (3.62)
∂x ∂y ω

T
The dissipation rate D (a negative quantity) is computed by the wave model and read from the
communication file. In SWAN, the dissipation rate may be computed from the bottom friction
(orbital motion), depth-induced breaking and whitecapping.
AF You can choose to apply the radiation stress or the dissipation rate to determine the wave-
induced forces.

3.8.2 Stokes drift and mass flux

In surface waves, fluid particles describe an orbital motion. The net horizontal displacement
for a fluid particle is not zero. This wave induced drift velocity, the so-called Stokes-drift,
is always in the direction of wave propagation. A particle at the top of the orbit beneath a
wave crest moves slightly faster in the forward direction than it does in the backward direction
beneath a wave trough. The mean drift velocity is a second order quantity in the wave height.
DR

The drift leads to additional fluxes in the wave averaged mass continuity equation.

The wave-induced mass fluxes MxS and MyS are found by integration of the components of
the Stokes drift uS and v S over the wave-averaged total water depth:
Z ζ
E
MxS = ρo uS dz = kx (3.63)
−d ω
Z ζ
E
MyS = ρ0 v S dz = ky (3.64)
−d ω

with E the wave energy defined as:

1 2
E = ρ0 gHrms . (3.65)
8

The mass fluxes MxS and MyS are computed by an interface program and are written to the
communication file.

Remarks:
⋄ The mass flux effect is only taken into account when D-Flow FM is coupled to D-Waves.
⋄ The velocities written to the communication file for use in D-Waves, and D-Water Quality
are based on the total flux velocities.
⋄ The Eulerian velocities, which may be used in comparisons with measurements at a
fixed location, are written to the hydrodynamic map and history files.

Deltares 25 of 562
 Conceptual description of hydrodynamic equations

The depth-averaged Stokes drift is given by:

MxS
US = , (3.66)
ρ0 (d + ζ)
MyS
VS = . (3.67)
ρ0 (d + ζ)

3.8.3 Enhancement of the bed shear-stress by waves

T
The boundary layers at the bed associated with the waves and the current interact non-linearly.
This has the effect of enhancing both the mean and oscillatory bed shear-stresses. The bed
shear-stress due to the combination of waves and current is enhanced beyond the value
which would result from a linear addition of the bed shear-stress due to waves, τ w , and the
bed shear-stress due to current τ c . For sediment transport modelling it is important to predict
AF the maximum bed shear-stress, τ max , while the current velocity and the turbulent diffusion
are determined by the combined wave-current bed shear-stress τ m .

Various, often very complex, methods exist to describe the bottom boundary layer under com-
bined current and wave action and the resulting virtual roughness. Soulsby et al. (1993a)
developed a parameterisation of these methods allowing a simple implementation and com-
parison of various wave-current interaction models: Fredsøe (1984); Myrhaug and Slaattelid
(1990); Grant and Madsen (1979); Huynh-Thanh and Temperville (1991); Davies et al. (1988);
Bijker (1967); Christoffersen and Jonsson (1985); O’ Connor and Yoo (1988); Van Rijn et al.
(2004). All these methods have all been implemented in D-Flow FM and can be applied in
2D and 3D modelling. However, as there are minor, but specific differences in determining
DR

certain quantities, such as determining the shear-stress at the bottom, we prefer to discuss
the 2D and 3D implementation separately.

Following Soulsby et al. (1993b), Figure 3.4 gives a schematic overview of the bed shear-
stresses for wave current interaction.

Soulsby et al. (1993b) fitted one standard formula to all of the models, each model having its
own fitting coefficients. The parameterisation of Soulsby for the time-mean bed shear-stress
is of the form:

|τ m | = Y (|τ c | + |τ w |) , (3.68)

with

Y = X {1 + bX p (1 − X)q } , (3.69)

and for the maximum bed shear-stress:

|τ max | = Z (|τ c | + |τ w |) , (3.70)

with

Z = 1 + aX m (1 − X)n . (3.71)

and:
|τ c |
X= , (3.72)
|τ c | + |τ w |
The value of the parameters a, b, p, q , m and n depends on the friction model which is
parameterised, and:

Deltares 26 of 562
 Conceptual description of hydrodynamic equations

T
AF Figure 3.4: Schematic view of non-linear interaction of wave and current bed shear-
stresses (from Soulsby et al. (1993b, Figure 16, p. 89))

|τ c | magnitude of the bed stress due to current alone

|τ w | magnitude of the bed stress for waves alone
|τ m | magnitude of the mean bed stress for combined waves and current
|τ max | magnitude of the maximum bed stress for combined waves and current.
DR

Remark:
⋄ The stresses τ m and τ max are assumed to have the same direction as τ c .

Following Soulsby et al. (1993b) the expressions for the parameters χ (= a, b, p, q, m, n)

and J (= I, J ; also depending on the friction model) have the form:
 

J
 
J

10 fw
χ = χ1 + χ2 |cos ϕ| + χ3 + χ4 |cos ϕ| log , (3.73)
C2D
in which:
C2D drag coefficient due to current
fw wave friction factor
ϕ the angle between the current direction and the direction of wave propagation.

As the radiation stress is always in the wave direction, we can derive ϕ from:

|U Fx + V Fy |
|cos ϕ| = . (3.74)
|U | |F |

Values of the parameters a, b, p, q and J in Equation (3.73) have been optimised by Soulsby
et al. (1993b), see Table 3.1 and Figure 3.5.

The bed shear-stress due to flow alone may be computed using various types of formulations
like Chézy, Manning or White-Colebrook, see Eqs. 3.12 to 3.15. The bed shear-stress due to
current alone can be written in the form:
gρ0 U |U |
τc = 2
. (3.75)
C2D

Deltares 27 of 562
 Conceptual description of hydrodynamic equations

T
Table 3.1: Fitting coefficients for wave/current boundary layer model

Model1 a1 a2 a3 a4 m1 m2 m3 m4 n1 n2 n3 n4 I
AF
FR84
MS90
-0.06
-0.01
1.70
1.84
-0.29
-0.58
0.29
-0.22
0.67
0.63
-0.29
-0.09
0.09
0.23
0.42
-0.02
0.75
0.82
-0.27
-0.30
0.11
0.19
-0.02
-0.21
0.80
0.67
HT91 -0.07 1.87 -0.34 -0.12 0.72 -0.33 0.08 0.34 0.78 -0.23 0.12 -0.12 0.82
GM79 0.11 1.95 -0.49 -0.28 0.65 -0.22 0.15 0.06 0.71 -0.19 0.17 -0.15 0.67
DS88 0.05 1.62 -0.38 0.25 1.05 -0.75 -0.08 0.59 0.66 -0.25 0.19 -0.03 0.82
BK67 0.00 2.00 0.00 0.00 0.00 0.50 0.00 0.00 0.00 0.50 0.00 0.00 1.00
CJ85 -0.01 1.58 -0.52 0.09 0.65 -0.17 0.18 0.05 0.47 -0.03 0.59 -0.50 0.64
OY88 -0.45 2.24 0.16 -0.09 0.71 0.27 -0.15 0.03 1.19 -0.66 -0.13 0.12 0.77

b1 b2 b3 b4 p1 p2 p3 p4 q1 q2 q3 q4 J
DR

FR84 0.29 0.55 -0.10 -0.14 -0.77 0.10 0.27 0.14 0.91 0.25 0.50 0.45 3.00
MS90 0.65 0.29 -0.30 -0.21 -0.60 0.10 0.27 -0.06 1.19 -0.68 0.22 -0.21 0.50
HT91 0.27 0.51 -0.10 -0.24 -0.75 0.13 0.12 0.02 0.89 0.40 0.50 -0.28 2.70
GM79 0.73 0.40 -0.23 -0.24 -0.68 0.13 0.24 -0.07 1.04 -0.56 0.34 -0.27 0.50
DS88 0.22 0.73 -0.05 -0.35 -0.86 0.26 0.34 -0.07 -0.89 2.33 2.60 -2.50 2.70
BK67 0.32 0.55 0.00 0.00 -0.63 0.05 0.00 0.00 1.14 0.18 0.00 0.00 3.00
CJ85 0.47 0.29 -0.09 -0.12 -0.70 0.13 0.28 -0.04 1.65 -1.19 -0.42 0.49 0.60
OY88 -0.06 0.26 0.08 -0.03 -1.00 0.31 0.25 -0.26 0.38 1.19 0.25 -0.66 1.50

VR04 Y = 0.0 and Z = 1.0

1
FR84=Fredsøe (1984), MS90=Myrhaug and Slaattelid (1990),
HT91=Huynh-Thanh and Temperville (1991), GM79=Grant and Madsen (1979), DS88=Davies et al. (1988),
BK67=Bijker (1967), CJ85=Christoffersen and Jonsson (1985), OY88=O’ Connor and Yoo (1988),
VR04=Van Rijn et al. (2004)

Deltares 28 of 562
 Conceptual description of hydrodynamic equations

T
AF
DR

Figure 3.5: Inter-comparison of eight models for prediction of mean and maximum bed
shear-stress due to waves and currents (from Soulsby et al. (1993b, Fig-
ure 17, p. 90))

Deltares 29 of 562
 Conceptual description of hydrodynamic equations

The magnitude of the wave-averaged bed shear-stress due to waves alone is related to the
wave orbital velocity near the bottom uorb and the friction coefficient fw :

1
|τ w | = ρ0 fw u2orb . (3.76)
2

The orbital velocity is computed from the linear wave theory and is given by:

1 √ Hrms ω
uorb = π , (3.77)

T
4 sinh (kH)
where the root-mean-square wave height Hrms and the wave period T (= 2π/ω) are read
from the communication file. The variation of the wave friction factor with relative orbital ex-
cursion at the bed under purely oscillatory flow is given by Swart (1974).
AF fw =
 
ks

0.00251 exp 5.21 A −0.19 ,
 
A
ks
A
> π2 ,
π
(3.78)
0.3, ≤ ,

ks 2

with:
uorb
A= , (3.79)
ω
ks is the Nikuradse roughness length-scale and ω is the wave angular frequency.
DR

As the bed is in rest and the equations are formulated in GLM co-ordinates, we must cor-
rect the bed shear-stress used in the momentum equations for the Stokes drift. The total or
effective bed shear stress is given by:

|τ m |
U − US ,


τb = (3.80)
|U |
S
where the components of the depth-averaged Stokes drift U are given by Eqs. 3.66 and
3.67.

3.9 Assumptions underlying D-Flow FM

In D-Flow FM the 1D (transverse and depth-averaged), 2D (depth-averaged) or 3D (multi-
layer) non-linear shallow water equations are derived from the three dimensional Navier-
Stokes equations for incompressible free surface flow. The following assumptions and ap-
proximations are applied:

⋄ The pressure is hydrostatic and the model is not capable of resolving the scales of short
waves. Therefore, the basic equations are averaged in analogy with turbulence introducing
so called radiation stresses.
⋄ The effect of variable density is only taken into account in the pressure term (Boussinesq
approximation).
⋄ In a Cartesian frame of reference, the effect of the Earth curvature is not taken into ac-
count. Furthermore, the Coriolis parameter is assumed to be uniform unless specifically
specified otherwise.
⋄ In spherical co-ordinates the inertial frequency depends on the latitude.
⋄ At the bed a slip boundary condition is assumed, a quadratic bed stress formulation is
applied.

Deltares 30 of 562
 Conceptual description of hydrodynamic equations

⋄ The formulation for the enhanced bed shear-stress due to the combination of waves and
currents is based on a 2D flow field, generated from the velocity near the bed using a
logarithmic approximation.
⋄ The equations of D-Flow FM are capable of resolving the turbulent scales (large eddy
simulation), but usually the hydrodynamic grids are too coarse to resolve the fluctuations.
Therefore, the basic equations are Reynolds-averaged introducing so-called Reynolds
stresses. These stresses are related to the Reynolds-averaged flow quantities by a turbu-
lence closure model.
⋄ The eddy viscosity is an-isotropic. The horizontal eddy viscosity and diffusivity coefficients
should combine both the effect of the 3D turbulent eddies and the horizontal motions that

T
cannot be resolved by the horizontal grid. The horizontal eddy viscosity is generally much
larger than the vertical eddy viscosity.
⋄ For large-scale flow simulations, the tangential shear-stress at lateral closed boundaries
can be neglected (free slip). In case of small-scale flow partial slip is applied along closed
boundaries.
⋄
AFFor large-scale flow simulations, the horizontal viscosity terms are reduced to a bi-harmonic
operator along co-ordinate lines. In case of small-scale flow the complete Reynold’s stress
tensor is computed. The shear-stress at the side walls is calculated using a logarithmic
law of the wall.
⋄ The drying and flooding procedure leads to a discontinuous movement of the closed
boundaries at tidal flats.
⋄ A continuity cell is set dry when all surrounding velocity points at the grid cell faces are
dry or when the actual water depth at the cell centre is below zero (negative volume).
⋄ The flux of matter through a closed wall and through the bed is zero.
⋄ The effect of precipitation on the water temperature is accounted for.
DR

⋄ In the σ co-ordinate system, the immediate effect of buoyancy on the vertical flow is
not considered. In D-Flow FM vertical density differences are taken into account in the
horizontal pressure gradients and in the vertical turbulent exchange coefficients. So the
application of D-Flow FM is restricted to mid-field and far-field dispersion simulations of
discharged water.
⋄ The boundary conditions for the turbulent kinetic energy and energy dissipation at the free
surface and bed assume a logarithmic law of the wall (local equilibrium).
⋄ In agreement with the aspect ratio for shallow water flow, the production of turbulence is
based on the vertical (and not the horizontal) gradients of the horizontal flow. In case
of small-scale flow (partial slip along closed boundaries), the horizontal gradients are in-
cluded in the production term.
⋄ Without specification of a temperature model, the heat exchange through the free surface
is zero. The heat loss through the bed is always zero.
⋄ If the total heat flux through the water surface is computed using a temperature excess
model the exchange coefficient is a function of temperature and wind speed and is de-
termined according to Sweers (1976). The natural background temperature is assumed
constant in space and may vary in time. In the more advanced heat flux formulation the
fluxes due to solar radiation, atmospheric and back radiation, convection, and heat loss
due to evaporation are modeled separately.
⋄ In the σ co-ordinate system the depth is assumed to be much smaller than the horizontal
length scale. For such a small aspect ratio the shallow water assumption is valid, which
means that the vertical momentum equation is reduced to the hydrostatic pressure rela-
tion. Thus, vertical accelerations are assumed to be small compared to the gravitational
acceleration and are therefore not taken into account.
⋄ In D-Flow FM the 3D turbulent eddies are bounded by the water depth. Their contribution
to the vertical exchange of horizontal momentum and mass is modelled through a vertical
eddy viscosity and eddy diffusivity coefficient (eddy viscosity concept). The coefficients
are assumed to be proportional to a velocity scale and a length scale. The coefficients

Deltares 31 of 562
 Conceptual description of hydrodynamic equations

may be specified (constant) or computed by means of an algebraic, k -τ or k -ε turbulence

model, where k is the turbulent kinetic energy, τ is the turbulent time scale and ε is the
dissipation rate of turbulent kinetic energy.

T
AF
DR

Deltares 32 of 562
 4 Conceptual description of transport equation

4.1 Introduction
In D-Flow FM, transport is formulated as
Z Z Z Z
d
c dV + c(u − v) • n dS = (K∇c) • n dS + s dV, (4.1)
dt
V (t) ∂V (t) ∂V (t) V (t)

T
where V (t) is a three-dimensional control volume, c is a concentration, u the flow velocity
field, v the velocity of the (vertically) moving control volume, K is a diagonal matrix K =
diag(κ, κ, κz ) with diffusion coefficients and s a source term. For two-dimensional (depth-
averaged) flow, we obtain

∂hc
AF ∂t
+ ∇ • (huc) = ∇ • (hκ∇c) + hs,

where h is the water depth. In case of three-dimensional (layer-averaged) flow, with ∆z a

(4.2)

layer thickness from z0 (x, y, t) to z1 (x, y, t), we obtain

∂∆z c
+ ∇ • (∆z uc) + [ωz1 c]z=z1 − [ωz0 c]z=z0 = ∇ • (∆z κ∇c)+
∂t    
∂c ∂c
κz − κ∇z1 • ∇c − κz − κ∇z0 • ∇c + ∆z s, (4.3)
∂z z=z1 ∂z z=z0
DR

T
where by u and ∇ still the horizontal components are meant, i.e. u = (u, v) and ∇ =
 T
∂ ∂
, and κz is the vertical diffusion coefficient. Furthermore ωz0 and ωz1 are the
∂x ∂y
velocity component normal and relative to the moving z = z0 and z = z1 layer interfaces
respectively. Note that taking c = 1 yields

∂z1 ∂z0
ωz1 + = ωz0 − ∇ • (∆zu) + , (4.4)
∂t ∂t
which, combined with a zero-flux condition at the bed, recursively defines ωz0 and ωz1 for all
layers.

We apply Equation (4.2) and Equation (4.3) to transport of

⋄ salinity,
⋄ temperature,
⋄ suspended sediment,
⋄ tracers,
⋄ other, intentionally not mentioned,

and ultimately to the water itself (the continuity equation) to obtain the relative layer interface
velocities as expressed by Equation (4.4).

4.2 Transport processes

Looking at the equations that govern transport of matter, we can identify three processes,
namely advection, diffusion and sources/sinks. The next sections will describe the relevant
user settings.

Deltares 33 of 562
 Conceptual description of transport equation

4.2.1 Advection
Advection of matter is expressed by the term ∇ • (huc) in Equation (4.2) in the case of
two-dimensional modelling.

Although not restricted to the advection of salinity only, the choices for all matter are set with
keyword limtypsa in the mdu-file, for example

[numerics]
limtypsa = 0 # first-order upwind, or

T
or

[numerics]
AF limtypsa = 4 # Monotonized-central limiter

In three dimensions, we make a distinction between horizontal advection ∇ • (∆z uc) and
vertical advection [ωz1 c]z=z1 −[ωz0 c]z=z0 in Equation (4.3). A higher-order numerical approx-
imation of these terms can be obtained by setting their "limiter type" to an appropriate value.
Setting the limiter type to "0" reduces the numerical approximation to a low-order upwind
method (i.e. severe limiting).

In three-dimensional modelling horizontal advection is similarly as in two dimension, but now

vertical advection can be selected with the keyword Vertadvtypsal in the mdu-file, i.e.
DR

[numerics]
Vertadvtypsal = 0 # no vertical advection

or

[numerics]
Vertadvtypsal = 6 # default

4.2.2 Diffusion
Diffusion of matter is expressed by the term ∇ • (hκ∇c) for two-dimensional modelling and
a similar and additional terms in three dimensions, see Equation (4.3).

Clearly, we have horizontal diffusivity κ and vertical diffusivity κz . The horizontal diffusivity κ
is a summation of
⋄ the molecular diffusivity κl . We use the following values:
 1
νl , salt,
 700

 1
ν, temperature,
κl = 6.7 l (4.5)
0ν , sediment,
 l


0νl , tracers,

where νl = 10−6 m2 /s is the kinematic viscosity,

⋄ a background diffusivity, user-specified as

Deltares 34 of 562
 Conceptual description of transport equation

spatially varying values by horizontaleddydiffusivitycoefficient in the

⋄
ext-file, or
⋄ a uniform value Dicouv in the mdu-file,
in that order of precedence, and
⋄ a contribution from turbulent transport expressed as νt /σt , where νt is the eddy viscosity
coefficient and σt is the turbulent Prandtl-Schmidt number for which the following values
are used:


 0.7, salt,
0.7, temperature,


T
σt = (4.6)

 1.0, sediment,

1.0, tracers.

Horizontal diffusion is turned off when Dicouv=0.

AF The user has to be aware of the following. The explicit nature of the horizontal diffusion terms
in the time-integration method imposes a condition on the time step for numerical stability.
Recall that we have a similar condition due to explicit horizontal advection. Although we
always decrease the time step to satisfy the advection-related time step criterion, we do not do
so for diffusion. Instead, diffusion is limited such that our time step is restricted by advection
only, or by a user-specified maximum time step if it is smaller. For further details, consult
Deltares (2025a).

Be aware that the modelled diffusion may be be smaller than anticipated. However, the ac-
DR

tual effective diffusion encountered may be (much) larger than anticipated due to numerical
diffusion of the advection scheme.

Not considering suspended sediment, and similar to the horizontal diffusivity, the vertical dif-
fusivity κz is a summation of
⋄ the molecular diffusivity κl , see Equation (4.5),
⋄ a background vertical diffusivity, user-specified as a uniform value Dicoww in the mdu-file,
and
⋄ a contribution from turbulent transport, similar to its horizontal counterpart, but with the
horizontal viscosity coefficient now replaced by the vertical (eddy) viscosity coefficient.

Time integration is performed with a method that does not impose an additional constraint on
the time step. Unlike horizontal diffusion which is limited to ensure numerical stability while
maintaining the time-step size, vertical diffusion is not limited.

Vertical diffusion is turned off when, again not considering suspended sediment:
⋄ if Dicoww=0,
⋄ if the water depth is smaller than a threshold 10−2 m.

For the vertical diffusivity of suspended sediment, see Deltares (2025d).

4.2.2.1 Time integration of horizontal diffusion

The advection and diffusion terms in the transport equation are integrated explicitly in time.
However, for 2D models with large horizontal diffusion coefficients this will lead to a large re-
duction of the time step. Therefore, an implicit time integration scheme has been implemented
for the horizontal diffusion term as well.To that purpose TransportAutoTimestepdiff

Deltares 35 of 562
 Conceptual description of transport equation

has been introduced. Via TransportAutoTimestepdiff = 3 the implicit time inte-

gration scheme is activated. The explicit time integration can be switched on via keyword
TransportAutoTimestepdiff = 0. In this case the horizontal diffusion coefficient is
probably reduced in order to satify the time step condition for stability. If so, then the following
message is written in the diagnostic file:

** INFO : Horizontal transport flux was limited for XX links.

T
with XX the number of links in which the horizontal diffusion coefficient has been reduced.
Per time step, a warning message displays the number of flow links in which the horizontal
diffusivity coefficient has been reduced. In order to prevent the diagnostic file becoming very
large, the warning is shown a maximum of ten times. The following message is written to the
diagnostic file at the end of the simulation:
AF
** INFO : Viscosity coefficient/Horizontal transport flux were limited on some links in the course of computation.

Another approach is to apply TransportAutoTimestepdiff = 1. Then, the horizon-

tal diffusion coefficient isn’t reduced, but the time step is probably reduced in order to satify the
stability condition. If so, then the simulation will require more computation time. Depending on
the application the user should choose the most suitable for for keyword TransportAutoTimestepdiff.
DR

The options described above represent so-called prognostic approaches, in which the trans-
port quantities are updated at each time step. A different approach is so-called diagnostic
modelling of transport processes. Then, the transport quantities aren’t updated during the
simulation. In this way, the initial conditions are being used and the transport concentrates are
frozen during the simulation. In case of horizontal density gradients the pressure term is rel-
evant for the computation of water levels. Via the diagnostic approach the density gradient is
taken into account in a simplified way. This avoids a possibly time step reduction for the trans-
port equation in case of large horizontal diffusion coefficients. The latter are often required
in depth-averaged simulations for modelling of salinity intrusion of estuaries. We remark that
in 3D this problem does not occur, because a turbulence closure model is applied and the
horizontal diffusion coefficients are small. In summary, a prognostic modelling of transport
processes is to be preferred, but in some applications, in particular in depth-averaged models
with large horizontal diffusion coefficients, diagnostic modelling can be a work-around. The
latter can be activitated via keyword DiagnosticTransport=1.

4.2.3 Sources and sinks

Sources and sinks may be provided by an entry in the new ext-file as follows:

[SourceSink]
id = SourceSink_1
locationFile = sourcesink01.pli
discharge = sourcesink_flows.bc
salinityDelta = sourcesink_changes.bc
...

Warning:

Deltares 36 of 562
 Conceptual description of transport equation

⋄ Deprecated: Source-sinks could also be specified in the old <*.ext> file. This will be-
come obsolete in an upcoming release and the example below is only kept for migration
purposes.

Sources and sinks may be provided by an entry in the old ext-file as follows:

quantity=discharge_salinity_temperature_sorsin

T
This simultaneously prescribes sources and sinks of
⋄ water volume itself (i.e. discharge),
⋄ salinity, and
⋄ temperature, and.
AF ⋄ any other constituents that are transported.

See section 7.4.11 for more details.

4.2.4 Forester filter

The vertical advection scheme in D-Flow FM 2D3D may cause nonphysical oscillations, or
wiggles, especially near regions of large gradients. The user has the option to suppress
salt and temperature wiggles with a filter inspired by the so-called Forester filter. This filter
also penalizes physically unstable stratification. The maximum number of iterations in the
DR

filter is controlled with keywords Maxitverticalforestersal for salt (default 100) and
Maxitverticalforestertem for temperature (default 0, i.e. no filtering).

4.3 Boundary and initial conditions for transport equation

The equations that govern transport of matter are complemented with boundary and initial
conditions. We make the distinction between "horizontal" boundaries, that are either "open"
or "closed", and vertical boundaries, only relevant for three-dimensional modelling.

4.3.1 Open boundary conditions

At "horizontal" open boundaries the following boundary conditions are applied, with or without
diffusion on the open boundary:
⋄ salt, temperature and tracers:
inflow: user-specified Dirichlet condition,
⋄ ⋄

outflow: homogeneous Neumann condition,

⋄ suspended sediment: see Deltares (2025d).

Horizontal diffusive transport through open boundaries is switched on by default and can be
switched off. The diffusive transport can be enabled or disabled by specifying the keyword
Diffusiononbnd in the mdu-file, and is valid for all open boundary types. Enable diffusive
transport on open boundaries (default)

[Numerics]
Diffusiononbnd=1

Deltares 37 of 562
 Conceptual description of transport equation

Disable diffusive transport on open boundaries

[Numerics]
Diffusiononbnd=0

The user-specified Dirichlet conditions are supplied in the usual manner through the ext-file,
for salt

T
quantity=salinitybnd

and for temperature

AF quantity=temperaturebnd

Boundaries conditions for multiple tracers may be defined by appending their name to the
tracerbnd keyword, for example

quantity=tracerbndMY_FIRST_TRACER
DR

and

quantity=tracerbndMY_SECOND_TRACER

When boundary conditions for transported constituents need to be prescribed using a three-
dimensional distribution (e.g. for stratified flows), the user can provide 3D boundary conditions.
This is described in section 10.5.

4.3.2 Closed boundary conditions

At "horizontal" closed boundaries zero-flux conditions are applied.

4.3.3 Vertical boundary conditions

At the "vertical" boundaries, i.e. at the bed and at the water surface, zero-flux conditions are
applied, except for temperature that is, see chapter 5 for further details on that matter.

4.3.4 Thatcher-Harleman boundary conditions

Consider (a part of) an open boundary where the flow reverts from outflowing to inflowing.
According to section 4.3.1, at that very moment a Dirichlet condition becomes effective and
a user-specified boundary value is prescribed. This value does in general not reflect the
true condition at the boundary and causes a discontinuous temporal behaviour. The so-
called Thatcher-Harleman boundary condition is intended to regularize this behaviour. The
actual value applied at the boundary is smoothly transformed from the last value under outflow

Deltares 38 of 562
 Conceptual description of transport equation

conditions to the user-specified value under inflow conditions within a user-specified return
time, which has to be specified in seconds. This return time is prescribed with the keyword
return_time in the “new style” external forcings file for boundary condition, for example

[boundary]
quantity = salinitybnd
locationfile = tfl_01.pli
forcingfile = tfl.bc
return_time = 250

T
See section C.6 for more details on this format.

4.3.5 Initial conditions

We will only consider intitial conditions for salinity, temperature and tracers. For initial sediment
AF concentrations, see Deltares (2025d).

Initial conditions are specified in three possible ways, namely

⋄ a horizontally spatially varying field in the usual way through the initial field file,
⋄ a vertical profile in three dimensions, horizontally uniformly distributed, for salinity and
temperature only in the initial field file, and
⋄ uniform values for salinity and temperature in the mdu-file.

In the initial field file we have

DR

[Initial]
quantity = initialsalinity

for the intial salinity, and

[Initial]
quantity = initialsalinitytop

for the initial salinity in the top layer in case of three-dimensional modelling. When specified,
the initial salinity field is linearly distributed from the "initialsalinity" in the lowest layer to the
"initialsalinitytop" in the top layer. When not specified, the initial salinity field is vertically
uniformly distributed.

The initial temperature field is prescribed with

[Initial]
quantity = initialtemperature

which in three dimensions is vertically uniformly distributed.

A horizontally uniformly distributed vertical profile of salinity and temperature can be pre-
scribed with initialverticalsalinityprofile and initialverticaltemperatureprofile
respectively, for example for salinity

Deltares 39 of 562
 Conceptual description of transport equation

[Initial]
quantity = initialverticalsalinityprofile
dataFile = inisal.pli
dataFileType = polygon
interpolationMethod = constant
operand = O

Warning:
⋄ Deprecated: The old external forcing file is being deprecated. The example below is

T
kept only for migration purposes:

QUANTITY=initialverticalsalinityprofile
FILENAME=inisal.pli
FILETYPE=10
AF METHOD=4
OPERAND=O

The polyline file contains (z , salinity) value pairs, where z is the vertical coordinate in meters.
For example for linearly varying salinity from 30 to 20 ppt from −10 to 0 m:

L1
2 2
-10 30
0 20
DR

The initial field of an arbitrary number of tracers are prescribed in the same way, except for
the user-specified tracername that is added to the keyword initialtracer, similar to the
tracer boundary conditions, for example

[Initial]
quantity=initialtracerMY_FIRST_TRACER

and

[Initial]
quantity=initialtracerMY_SECOND_TRACER

Default values for salinity and temperature are defined in the mdu-file with Initialsalinity
and Initialtemperature respectively.

4.4 Introduction to sediment transport

Note: Sediment transport in 3D modelling is β -functionality.

The sediment transport and morphology module supports both bedload and suspended load
transport of non-cohesive sediments and suspended load of cohesive sediments. For schema-
tisation we distinguish "mud" (cohesive suspended load transport), "sand" (non-cohesive bed-
load and suspended load transport) and "bedload" (non-cohesive bedload only or total load
transport) fractions. For a detailed description we refer to Deltares (2025d).

Deltares 40 of 562
5 Conceptual description of heat flux models
This chapter has a lot of similarities with the Delft3D-FLOW manual. The difference is that in
Delft3D-FLOW five heat flux models are implemented, whereas in D-Flow FM only two models
are implemented. These are the most complete heat flux model, the so called Composite
heat flux model (i.e. the Ocean heat flux model nr 5 in Delft3D-FLOW) and the most simple
model, the Excess temperature model (model nr 3 in Delft3D-FLOW). In D-Flow FM, the
parameter that sets the temperature model is called Temperature in the mdu-file. We kept
the numbering of Delft3D-FLOW. When specifying Temperature=1, the temperature is
taken into account in the transport solver and in the equation of state, but heat fluxes through

T
the water surface are not taken into account. This may be useful when mixing is the primary
factor that determines the temperature distribution.

The heat radiation emitted by the sun reaches the earth in the form of electromagnetic waves
with wavelengths in the range of 0.15 to 4 µm. In the atmosphere the radiation undergoes
AF
scattering, reflection and absorption by air, cloud, dust and particles. On average neither the
atmosphere nor the earth accumulates heat, which implies that the absorbed heat is emitted
back again. The wavelengths of these emitted radiations are longer (between 4 and 50 µm)
due to the lower prevailing temperature in the atmosphere and on Earth. Schematically the
radiation process, along with the heat flux mechanisms at the water surface, is shown in
Figure 5.1.
DR

Figure 5.1: Overview of the heat exchange mechanisms at the surface

Legend for Figure 5.1:

Qsc radiation (flux) for clear sky condition in [J/m2 s]
Qco heat loss due to convection (sensible) in [J/m2 s]
Qsr reflected solar radiation in [J/m2 s]
Qs solar radiation (short wave radiation) in [J/m2 s]
Qsn net incident solar radiation (short wave), = Qs − Qsr

Deltares 41 of 562
 Conceptual description of heat flux models

Qa atmospheric radiation (long wave radiation) in [J/m2 s]

Qan net incident atmospheric radiation (long wave)
Qar reflected atmospheric radiation in [J/m2 s]
Qbr back radiation (long wave radiation) in [J/m2 s]
Qev heat loss due to evaporation (latent) in [J/m2 s]

In D-Flow FM the heat exchange at the free surface is modeled by taking into account the sep-
arate effects of solar (short wave) and atmospheric (long wave) radiation, and heat loss due to
back radiation, evaporation and convection. The heat losses due to evaporation and convec-
tion are functions of the wind speed. In absence of wind, these terms become zero. However,

T
since water vapor is lighter than air, water may be cooled by evaporation and convection even
in a no wind situation. The terms are called Qevfree and Qcofree respectively.

Excess temperature model - heat flux model 3

AF
In the Excess temperature model the heat exchange flux at the air-water interface is computed
based upon the prescribed background air temperature, the computed water temperature of
the top layer and the prescribed wind speed. This relatively simple model is sometimes used
in intake–outfall design studies. It can be applied when the temperature mixing process itself
is more relevant than the actual heat loss through the air water interface. The applied heat
exchange coefficient is mainly a function of the windspeed and water surface temperature.

The excess temperature model 3 is based on Sweers (1976), the heat exchange flux is rep-
resented by a bulk exchange formula:

Qtot = −λ (Ts − Tback ) , (5.1)

DR

with Ts the water temperature at the free surface and Tback the natural background tempera-
ture, both in ◦ C.

The heat exchange coefficient λ is a function of the surface temperature Ts and the wind
speed U10 . It is derived by linearization of the exchange fluxes for back radiation, evaporation
and convection. The following relation was derived by Sweers (1976):

λ = 4.48 + 0.049Ts + f (U10 ) 1.12 + 0.018Ts + 0.00158Ts2 .

(5.2)

Composite - heat flux model 5

The heat flux model 5 following Gill (1982) and Lane (1989) was calibrated for the North Sea
and successfully applied for great lakes.

In the Composite heat flux model, the relative humidity in [%], air temperature in [◦ C] and
cloudiness in [%] are prescribed.

These quantities may be either uniform or specially varying. In the external forcingsfile one
may have:

QUANTITY =humidity_airtemperature_cloudiness
FILENAME =meteo.hac
FILETYPE =6
METHOD =3
OPERAND =O

For example input files see example directories:

Deltares 42 of 562
 Conceptual description of heat flux models

f20_heat_flux/**/

The effective back radiation and the heat losses due to evaporation and convection are com-
puted by the model. Additionally, when air and water densities and/or temperatures are such
that free convection occurs, free convection of latent and sensible heat is computed by the
model.

Normally, solar radiation is computed based upon time of day, position on earth and cloudi-
ness. However, if solar radiation was measured, it can also be prescribed via the solar radia-
tion (in [W/m2 ]) according to:

T
QUANTITY =humidity_airtemperature_cloudiness_solarradiation
FILENAME =meteo.hacs
FILETYPE =6
METHOD =3
AF OPERAND =O

We remark that the solar radiation doesn’t contain the correction factor (1 − albedo). Thus,
the solar radiation values prescribed by the user will be multiplied by this factor.

In both heat flux models, the wind forcing may be uniform or spatially varying.

If wind is uniform, the wind speed and direction are prescribed, wind speed is in m/s, and
direction follows nautical convention: 0 means wind coming from North, 90 means wind is
coming from East. In the external forcings file specify, e.g.:
DR

QUANTITY=windxy
FILENAME=zeg99-10.wnd
FILETYPE=2
METHOD=1
OPERAND=O

If wind is spatially varying, the air pressure is also prescribed:

QUANTITY =airpressure_windx_windy
FILENAME =CSM_2015.apwxwy
FILETYPE =6
METHOD =3
OPERAND =O

Air pressure is in [Pa], wind x- and y -components are given [m/s].

For the physical background of the heat exchange at the air-water interface and the definitions,
we refer to Sweers (1976) for the Excess temperature model (Temperature=3), and to Gill
(1982) and Lane (1989) for the Ocean heat flux model (Temperature=5).

5.1 Heat balance

The total heat flux through the free surface reads:
Qtot = Qsn + Qan − Qbr − Qev − Qco − Qevf ree − Qcof ree , (5.3)
with:

Deltares 43 of 562
 Conceptual description of heat flux models

Qsn net incident solar radiation (short wave)

Qan net incident atmospheric radiation (long wave)
Qbr back radiation (long wave)
Qev evaporative heat flux (latent heat)
Qco convective heat flux (sensible heat)
Qevf ree evaporative heat flux (free convection latent heat)
Qcof ree convective heat flux (free convection sensible heat).

The subscript n refers to a net contribution. Each of the heat fluxes in Equation (5.3) will be
discussed in detail.

T
The change in temperature in the top layer Ts [◦ C] is given by:

∂Ts Qtot
= , (5.4)
∂t ρw cp ∆zs
AF where Qtot [J/m2 s] is the total heat flux through the air-water surface, cp (= 3930 J kg−1 K) is
the specific heat capacity of sea water, ρw is the specific density of water [kg/m3 ] and ∆zs
[m] is the thickness of the top layer. As in Delft3D-FLOW, the heat exchange at the bed is
assumed to be zero. This may lead to over-prediction of the water temperature in shallow
areas. Also the effect of precipitation on the water temperature is not taken into account.

Remarks:
⋄ The temperature T is by default expressed in ◦ C. However, in some formulas the abso-
lute temperature T̄ in K is used. They are related by:
DR

T̄ = T + 273.15. (5.5)

⋄ In Equation (5.4) the total incoming heat flux is absorbed with exponential decay as a
function of depth. See the parameter Secchi-depth in the mdu-file.

5.2 Solar radiation

The short-wave radiation emitted by the sun that reaches the earth surface under a clear sky
condition can be evaluated by means of:

⋄ Applying Stefan-Boltzmann’s law for radiation from a black-body:

Q = σ T̄ 4 (5.6)

with σ = Stefan-Boltzmann’s constant = 5.67 × 10−8 J/(m2 s K4 ) and T̄ the (absolute)

temperature in K.

⋄ Direct measurements.

The incoming short-wave solar radiation through a clear sky at ground level Qsc is about 0.76
of the flux incident at the top of the atmosphere (Gill, 1982):

0.76S sin(γ), sin(γ) ≥ 0,
Qsc = (5.7)
0.0, sin(γ) < 0.

The solar constant S = 1 368 J/(m2 s) or W/m2 . This is the average energy flux at the mean
radius of the Earth.

Deltares 44 of 562
 Conceptual description of heat flux models

T
AF
Figure 5.2: Co-ordinate system position Sun
δ : declination; θ: latitude; ωt: angular speed

The incoming energy flux at the water surface depends on the angle (declination) between
the incoming radiation and the Earth’s surface. This declination depends on the geographical
DR

position on the Earth and the local time. The Earth axis is not perpendicular to the line
connecting the Sun with Earth. This tilting (angle δ ) varies with the time of the year and it
leads to a seasonal variation of the radiation flux. At June 21, the declination is maximal,
23.5 degrees. Of course, by the rotation of the Earth the solar radiation also varies during the
day. Near twelve o’clock local time, the sun elevation above the horizon is maximal. For an
overview of the angles used to determine the solar elevation angle γ , see Figure 5.2.

The temporal and latitude-dependent solar elevation angle γ is estimated by:

   
πϕ πϕ
sin (γ) = sin (δ) sin − cos (δ) cos cos (ω1 t) (5.8)
180 180
with:
23.5π
δ= cos(ω0 t − 2.95), (5.9)
180
where ω0 is the frequency of the annual variation and ω1 the frequency of the diurnal variation;
ϕ is the latitude.

A part of the radiation that reaches the water surface is reflected. The fraction reflected or
scattered (surface albedo) is dependent on latitude and season. Additionally, cloud cover
will reduce the magnitude of the radiation flux that reaches the sea surface. The cloudiness
is expressed by a cloud cover fraction Fc , the fraction of the sky covered by clouds. The
correction factor for cloud cover is an empirical formula. The absorption of solar radiation
is calculated (Gill, 1982) as the product of the net downward flux of short wave-radiation in
cloudless conditions and factors correcting for reflection and cloud cover:

Qsn = Qs − Qsr = (1 − α) Qsc (1.0 − 0.4Fc − 0.38Fc2 ), (5.10)

with:

Deltares 45 of 562
 Conceptual description of heat flux models

Qsn net heat radiation (flux) from the Sun

Qs solar radiation (short wave radiation) in [J/m2 s]
Qsr reflected solar radiation in [J/m2 s]
Qsc radiation (flux) for clear sky condition
α albedo (reflection) coefficient (=0.06)
Fc fraction of sky covered by clouds (user-defined input)

Finally, not all of the radiation is absorbed at the water surface. A part is transmitted to deeper
water. Short waves can penetrate over a distance of 3 to 30 meters, depending on the clarity
of the water, while the relatively longer waves are absorbed at the surface. The Secchi depth

T
HSecchi (m), is a measure of the transparency of the water.

The formulation for the (remaining) under-water light in the water column (W/m2) is based
on the so-called Lambert-Beer Law, which can be derived from the following linear first-order
ordinary differential equation (ODE):
AF dQsn
dz
= −γQsn , (5.11)

with γ the extinction coefficient (1/m). The total extinction coefficient of visible light γ deter-
mines the visibility of a Secchi disk under water. The following approximation is used for the
relation between γ and Secchi depth HSecchi :

1.7
γ= (5.12)
HSecchi
The Secchi depth is prescribed by the user at input (normal values are in the range from 2
DR

to 30 meter). This results in an exponential function of the distance z from the water surface
for the visible light (remaining) in the water column, the Lambert-Beer law (assuming constant
γ ):
Qsn (z) = e−γz Q0sn , (5.13)

with:
Q0sn the incoming nett solar radation Qsn that reaches the water surface
γ extinction coefficient (measured) in m−1 , also related to the so-called Secchi-
depth γ = H 1.7
Secchi
z distance to the water surface in meters.

The vertical coordinate z in Equation (5.13) is the distance to the water surface in meters. The
absorbed flux of light (W/m2) in an internal computational layer k with coordinate ztop (upper
vertical interface of the cell) and zbot (lower vertical interface of the cell) is given by:

Qsn (k) = Qsn (ztop ) − Qsn (zbot ) (5.14)

= e−γztop − e−γzbot Q0sn


(5.15)

Secchi disc measurements are, by nature of the observation method, a good proxy for the
penetration of visible light in water. The penetration of visible light depends on the composition
of the water (suspended and dissolves substances). The penetration of near-infrared (> 700
nm) light depends on water only, not on its composition. The Secchi depth is, therefore, not a
good proxy for the penetration depth of near-infrared light. For that reason, we implemented
the option to incorporate the penetration of solar radiation in the water column using a blend
of two Lambert-Beer Law profiles, based on the work of Wunderlich (1972). This option
requires a user-defined ratio β (0 ≤ β ≤ 1), which determines the portion of incoming solar

Deltares 46 of 562
 Conceptual description of heat flux models

radiation in the near-infrared spectrum, which is absorbed near the free-surface. The user
can prescribe the thickness of this near-surface layer, i.e. a ’shallow’ Secchi depth HSecchi2 .
The rest (1 − β ) is the visible light, absorbed with the (normal) user defined Secchi-depth
HSecchi .

Using this approach, the nett incoming solar radiation (after reduction through cloud coverage
and surface reflection using the Albedo coefficient) is split into two contributions:

⋄ βQsn , the near-infrared wave portion, which is absorbed at the surface (HSecchi2 ) and
⋄ (1 − β) Qsn , the remainder part, which is absorbed in deeper water (HSecchi ).

T
Finally, the absorbed flux of light (W/m2) in an internal computational layer k is then given by:

Qsn (k) = (1 − β) e−γztop − e−γzbot + β e−γ2 ztop − e−γ2 zbot Q0sn

(5.16)

with: γ2 the ’shallow’ extinction coefficient (measured) in m−1 , related to the ’shallow’ Secchi-
AF depth γ2 = H 1.7
Secchi2

In the mdu-file, the user can switch on this functionality by specifying the HSecchi2 and β using
the following keywords:

⋄ HSecchi2 using Secchidepth2 and

⋄ β using Secchidepth2fraction (with 0 ≤ β ≤ 1).

Note: It should be noted, that the term ’shallow’ Secchi depth is formally not appropriate,
since a Secchi disk would not be visible in infrared light, but we stick to the same naming to
DR

clarify users that the two depths HSecchi and HSecchi2 are related.

5.3 Atmospheric radiation (long wave radiation)

Atmospheric radiation is primarily due to emission of absorbed solar radiation by water vapour,
carbon dioxide and ozone in the atmosphere. The emission spectrum of the atmosphere is
highly irregular. The amount of atmospheric radiation that reaches the earth is determined by
applying the Stefan-Boltzmann’s law that includes the emissivity coefficient of the atmosphere
ε. Taking into account the effect of reflection by the surface and reflection and absorption by
clouds, the relation for the net atmospheric radiation Qan reads (Octavio et al., 1977):

Qan = (1 − r) εσ T̄a4 g (Fc ) , (5.17)

where T̄a is the air temperature (in K) and the reflection coefficient r = 0.03. The emissivity
factor of the atmosphere ε may depend both on vapour pressure and air temperature. The
emissivity of the atmosphere varies between 0.7 for clear sky and low temperature and 1.0.
The presence of clouds increases the atmospheric radiation. This is expressed in the cloud
function g (Fc ).

with Ta the air temperature (in ◦ C). The cloud function g (Fc ) in Equation (5.17) is given by:

g (Fc ) = 1.0 + 0.17Fc2 .2 − 9 (5.18)

The linearisation of Equation (5.17) is carried out around Ta = 15 ◦ C.

Remark:
⋄ The atmospheric radiation is part of the total long-wave radiation flux, the so-called
effective back radiation, see section 5.5.

Deltares 47 of 562
 Conceptual description of heat flux models

5.4 Back radiation (long wave radiation)

Water radiates as a near black body, so the heat radiated back by the water can be described
by Stefan-Boltzmann’s law of radiation, corrected by an emissivity factor ε = 0.985 of water
(Sweers, 1976; Octavio et al., 1977) and the reflection coefficient for the air-water interface
r = 0.03:
Qbr = (1 − r) εσ T̄s4 , (5.19)

with T̄s the (absolute) water surface temperature in K.

T
5.5 Effective back radiation
The total net long wave radiation flux is computed. This is called the effective back radiation:

Qeb = Qbr − Qan . (5.20)

AF The atmospheric radiation depends on the vapour pressure ea , see section 5.6, the air tem-
perature Ta and the cloud cover Fc . The back radiation depends on the surface temperature
Ts .

The effective back radiation Qeb is computed following:

√
Qeb = εσ T̄s4 (0.39 − 0.05 ea ) 1.0 − 0.6Fc2 ,


(5.21)

with the actual vapour pressure ea given by Equation (5.26).

DR

5.6 Evaporative heat flux

Evaporation is an exchange process that takes place at the interface between water and air
and depends on the conditions both in the water near the surface and the air above it. The
evaporation depends on meteorological factors (wind-driven convection) and vapour pres-
sures.

Forced convection of latent heat

The latent heat flux due to forced convection for the ocean heat flux model reads:

Qev,forced = LV ρa f (U10 ) {qs (Ts ) − qa (Ta )} , (5.22)

with qs and qa the specific humidity of respectively saturated air and remote air (10 m above
water level):

0.62es
qs (Ts ) = , (5.23)
Patm − 0.38es
0.62ea
qa (Ta ) = . (5.24)
Patm − 0.38ea

The saturated and remote vapour pressures es and ea are given by:
0.7859+0.03477Ts
es = 10 1.0+0.00412Ts , (5.25)
0.7859+0.03477Ta
ea = rhum 10 1.0+0.00412Ta . (5.26)

Deltares 48 of 562
 Conceptual description of heat flux models

With Lv the latent heat of vaporisation in J/kg water:

Lv = 2.5 106 − 2.3 103 Ts . (5.27)

The wind function in Equation (5.22) is defined as:

f (U10 ) = ce U10 , (5.28)

The default value for the Dalton number ce in the Composite heat flux model reads ce =

T
0.0013. This value should be close to the Cd coefficient that is used in the computation of
wind stresses. The exchange coefficients of latent heat and momentum transfer are closely
related. Specifying a negative Dalton number in the mdu file forces the use of the specified
Cd coefficient, thus taking into account the specified dependency between windspeed and
the Cd coefficient.
AF
Here rhum is the relative humidity in [-].

Remarks:
⋄ The relative humidity rhum is specified in the input files in percentages.
⋄ When the computed E is negative, it is replaced by zero, assuming that it is caused by
modelling misfit and not by the actual physical process of water condensation out of the
air into the water. The same applies to the part associated with free convection.

For the excess temperature model, the wind speed function f (U10 ) following Sweers (1976)
DR

is used:
0.05
5.0 × 106

f (U10 ) = (3.5 + 2.0U10 ) , (5.29)
Sarea
where Sarea is the exposed water surface in m2 , defined in the input and fixed for the whole
simulation. The coefficients calibrated by Sweers were based on the wind speed at 3 meter
above the free surface; the coefficients in Equation (5.29) are based on the wind speed 10
meter above the water level.

Free convection of latent heat

Loss of heat due to evaporation occurs not only by forced convection, wind driven, but also
by free convection. Free convection is driven by buoyant forces due to density differences
(by temperature and/or water vapour content) creating unstable conditions in the atmospheric
boundary layer. Evaporation due to free convection is important in circumstances where in-
verse temperature/density gradients are present and wind speeds are almost negligible so
that the amount of forced convection is small. Neglecting free convection in this situation will
lead to underestimating the heat loss. (Ryan et al., 1974) developed a correction to the wind
function, accounting for free convection. The derivation of evaporation by just free convection
is based on the analogy of heat and mass transfer.

The latent heat flux due to free convection reads:

Qev,free = ks LV ρa (qs − qa ) , (5.30)

with the average air density:

ρa0 + ρa10
ρa = , (5.31)
2

Deltares 49 of 562
 Conceptual description of heat flux models

and with the heat transfer coefficient defined as:

if ρa10 − ρa0 ≤ 0
(
0
ks = n
gα2
o1/3 (5.32)
cf r.conv νair ρa
(ρa10 − ρa0 ) if ρa10 − ρa0 > 0

where the coefficient of free convection cf r.conv was calibrated to be 0.14, see (Ryan et al.,
1974). The viscosity of air νair is assumed to have the constant value 16.0 × 10−6 m2 /s. The
molecular diffusivity of air α m2 /s is defined as
νair

T
α= , (5.33)
σ
with σ = 0.7 (for air) the Prandtl number. In Equation (5.30), the saturated air density is given
by:
AF ρa0 =
100Patm −100es
Rdry
Ts + 273.15
+ 100es
Rvap
, (5.34)

the remote air density (10 m above the water level):

100Patm −100ea 100ea
Rdry
+ Rvap
ρa10 = , (5.35)
Tair + 273.15
where Rdry is the gas constant for dry air: 287.05 J/(kg K) and Rvap is the gas constant for
water vapour: 461.495 J/(kg K). The specific humidity of respectively saturated air and remote
DR

air (10 m above the water level), qs and qa are given by Equation (5.23) and Equation (5.24).
The saturated and remote vapour pressure es and ea are defined in Equation (5.25) and
Equation (5.26).

The total heat flux due to evaporation then results from adding the forced convection of latent
heat in Equation (5.22) and the free convection of latent heat in Equation (5.30):

Qev = Qev,forced + Qev,free . (5.36)

5.7 Convective heat flux

In the Ocean heat flux model, the convective heat flux is split into two parts, just as the evap-
orative heat flux. The convective heat flux is divided into a contribution by forced convection
and a contribution by free convection.

Forced convection of sensible heat

The sensible heat flux due to forced convection is computed by:

Qco,forced = ρa cp g (U10 ) (Ts − Ta ) , (5.37)

with cp the specific heat of air. It is considered constant and taken to be 1 004.0 J/(kg K). The
wind-speed function g (U10 ) is defined following Gill (1982):

g (U10 ) = cH U10 , (5.38)

with cH the so-called Stanton number. The default value of the Stanton number reads cH =
0.0013.

Deltares 50 of 562
 Conceptual description of heat flux models

Free convection of sensible heat

Qco,free = ks ρa cp (Ts − Ta ) , (5.39)

with the heat transfer coefficient ks given by Equation (5.32).

The total heat flux due to convection then results from adding the forced convection of sensible
heat in Equation (5.37) and the free convection of sensible heat in Equation (5.39):

T
Qco = Qco,forced + Qco,free . (5.40)

AF
DR

Deltares 51 of 562
 6 Getting started with Graphical User Interface

6.1 Introduction
This chapter gives an overview of the basic features of the D-Flow FM User Interface and
will guide you through the main steps to set up a D-Flow FM model. For a more detailed
description of the GUI features you are referred to chapter 7. For technical documentation
you are referred to Deltares (2025a).

T
6.2 Overview of D-Flow FM GUI
When you start the application for the first time the lay-out might look like Figure 6.1. The
basic lay-out consists of the following items:

⋄ Ribbon - top
⋄
AF ⋄
⋄
Project window - up left
The central window, containing the Start Page
Messages and Time Navigator window - down centre
⋄ Toolbox, Chart, Region, Map and Operations window - to the right
⋄ Properties window - down left
DR

Figure 6.1: Start-up lay-out D-Flow FM User Interface

All the windows can be customized/hidden according to your own preferences.

These settings will be automatically saved for the next time you start the application.

The most important windows for the D-Flow FM plugin are the Project, Map, Messages,
Time Navigator and Properties windows. The central window displays the Start Page. Here
the Map view or specific editors will be displayed.

The contents of these windows are briefly discussed in the subsections below.

Deltares 52 of 562
 Getting started with Graphical User Interface

6.2.1 Project window

After adding or importing a D-Flow FM model (see section 6.5.1 and section 6.5.2), the Project
window will be extended with D-Flow FM specific features (see Figure 6.2). The Project
window provides you with the basic steps to set up a D-Flow FM model.

The Project window consists of the following features:

General general model information such as depth layer specification, model

coordinate system and angle of latitude and longitude
Area geographical (GIS based) features, such as observation points, struc-

T
tures, dry points and land boundaries
Grid computational grid
Bed Level model bed level
Time Frame model time frame and time step
Processes active physical processes in the model such as salinity, temperature,
AF Initial Conditions
Boundary Conditions
wind and tide generating forces
initial conditions for water levels and other physical processes
model boundaries and boundary condition specification
Physical Parameters physical settings for processes such as roughness, viscosity, wind
and temperature
Sources and Sinks location and time series specification for point sources and sinks
Numerical Parameters numerical simulation settings
Output Parameters output specification
Output output after running the simulation
DR

Upon clicking the items in the Project window the corresponding tab (in case of non-geographic
model settings), attribute table (in case of geographic model settings) or editor view (in case
of advanced editing options) will open in the central window. Using the right mouse button
gives options such as importing/exporting model data.

Figure 6.2: Project window of D-Flow FM plugin

Deltares 53 of 562
 Getting started with Graphical User Interface

6.2.2 The central window

The central window shows the contents of the map or the editor you are working with. Multiple
maps and editors may be docked at the central window location; each accessible as a tabs
along the top (see Figure 6.3). The map is used to edit geographic model data, the editor for
the overall model settings. Moreover, the contents of the central window can also be a specific
editor such as the time point editor or the boundary condition editor. Each of these editors will
open as a separate tab.

T
AF
Figure 6.3: The central window with a map and contents of the D-Flow FM model
DR

6.2.3 Settings window

Figure 6.4: The model Settings window with General settings tab enabled

Deltares 54 of 562
 Getting started with Graphical User Interface

6.2.4 Map window

The Map window allows the user to control the visibility of the contents of the central map
using checkboxes. Furthermore, the user can add (wms) layers, such as satellite imagery or
open street maps (see Figure 6.5).

Note: Please note that the map usually has a different coordinate system than the model. In
rendering the model attributes they are transformed to the map coordinate system (for visual
inspection on the map), but the model will be saved in the model coordinate system.

T
AF
Figure 6.5: Map window controlling map contents
DR

6.2.5 Messages window

The Message window (Figure 6.6) provides a log of information on the recent activities in the
User Interface. It also provides warning and error messages.

Figure 6.6: Log of messages, warnings and errors in message window

6.2.6 Time Navigator window

The Time Navigator (Figure 6.7) can be used to step through time dependent model output
and other time dependent geographic features on the map.

Figure 6.7: Time Navigator window in D-Flow FM User Interface

Deltares 55 of 562
 Getting started with Graphical User Interface

6.3 Dockable views

The User Interface offers lots of freedom to customize dockable views, which are discussed
in this section.

6.3.1 Docking tabs separately

Within the User Interface the user can dock the separate windows according to personal
preferences. These preferences are then saved for future use of the framework. An example
of such preferences is presented in Figure 6.8, where windows have been docked on two

T
screens.

AF
Figure 6.8: Docking windows on two screens within the User Interface.

6.3.2 Multiple tabs

DR

In case two windows are docked in one view, the underlying window (tab) can be brought to
the front by simply selecting the tab, as is shown here.

Figure 6.9: Bringing the Time Navigator window to the front

By dragging dockable windows with the left mouse button and dropping the window left, right,
above or below another one the graphical user interface can be customized according to
personal preferences. Here an example of the Time Navigator window being docked to the
right of the Messages window.

Figure 6.10: Docking the Time Navigator window.

Additional features are the possibility to remove or (auto) hide the window (top right in Fig-
ure 6.10). In case of removal, the window can be retrieved by two left mouse-clicks on Time
Navigator in the View ribbon. Hiding the Properties window results in:

Deltares 56 of 562
 Getting started with Graphical User Interface

T
Figure 6.11: Auto hide the Properties window

6.4 Ribbons and toolbars

AF The user can access the toolbars arranged in ribbons. Model plug-ins can have their own
model specific ribbon. The ribbon may be auto collapsed by activating the Collapse the Ribbon
button when right-mouse-clicking on the ribbon.

6.4.1 Ribbons (shortcut keys)

The User Interface makes use of ribbons, just like Microsoft Office. You can use these ribbons
for most of the operations. With the ribbons comes shortcut key functionality, providing short-
cuts to perform operations. If you press Alt, you will see the letters and numbers to access
the ribbons and the ribbon contents (i.e. operations). For example, Alt + H will lead you to
DR

the Home-ribbon (Figure 6.12).

Note: Implementation of the shortcut key functionality is still work in progress.

Figure 6.12: Perform operations using the shortcut keys

6.4.2 File
The left-most ribbon is the File ribbon. It has menu-items comparable to most Microsoft
applications. Furthermore, it offers users save and open functionality, as well as the Info and
Options dialogs, as shown in Figure 6.13 and Figure 6.14.

Deltares 57 of 562
 Getting started with Graphical User Interface

T
AF
Figure 6.13: The File ribbon.
DR

Figure 6.14: The User Interface options dialog.

Deltares 58 of 562
 Getting started with Graphical User Interface

6.4.3 Home
The second ribbon is the Home ribbon (Figure 6.15). It harbours some general features for
clipboard actions, addition of items, running models, finding items within projects or views,
and help functionality.

T
Figure 6.15: The Home ribbon.
AF
6.4.4 View
The third ribbon is the View ribbon (Figure 6.16). Here, the user can show or hide windows.
DR

Figure 6.16: The View ribbon.

6.4.5 Tools
The fourth ribbon is the Tools ribbon (Figure 6.17). By default, it contains only the Open
Case Analysis View tool. Some model plug-ins offer the installation of extra tools that may be
installed. These are documented within the user documentation of those model plug-ins.

Figure 6.17: The Tools ribbon contains just the Data item.

6.4.6 Map
The last ribbon is the Map ribbon (Figure 6.18).

Figure 6.18: The Map ribbon.

Deltares 59 of 562
 Getting started with Graphical User Interface

This will be used heavily, while it harbours all Geospatial functions, like:
⋄ Decorations for the map
North arrow
⋄ ⋄ ⋄ ⋄

Scale bar
Legend
...
⋄ Tools to customize the map view
Select a single item
⋄ ⋄ ⋄ ⋄ ⋄ ⋄ ⋄

T
Select multiple items by drawing a curve
Pan
Zoom to Extents
Zoom by drawing a rectangle
Zoom to Measure distance
AF ...
⋄ Edit polygons, for example within a network, basin, or waterbody
Move geometry point(s)
⋄ ⋄ ⋄

Add geometry point(s)

Remove geometry point(s)
⋄ Addition of Area elements, such as
Add 2D Cross-section
⋄ ⋄ ⋄ ⋄

Add 2D Structure
Add 2D Pump
DR

...

Still, all functions of the category can be activated as they will appear in the drop-down panel.

6.4.7 Scripting
When you open the scripting editor in the User Interface, a Scripting ribbon category will
appear. This ribbon has the following additional options (see also Figure 6.19), which are
described in Table 6.1:

Figure 6.19: The scripting ribbon within the User Interface.

Table 6.1: Functions and their descriptions within the scripting ribbon of the User Inter-
face.

Function Description

Run script Executes the selected text. If no text is selected then it will
execute the entire script
Clear cached variables Clears all variables and loaded libraries from memory

Deltares 60 of 562
 Getting started with Graphical User Interface

Table 6.1: Functions and their descriptions within the scripting ribbon of the User Inter-
face.

Function Description

Debugging Enables/Disables the debug option. When enabled you can

add breakpoint to the code (using F9 or clicking in the mar-
gin) and the code will stop at this point before executing the
statement (use F10 (step over) or F11 (step into) for a more
step by step approach)

T
Python variables Show or hide python variables (like _var_) in code comple-
tion
Insert spaces/tabs Determines if spaces or tab characters are added when
pressing tab
AF Tab size

Save before run

Sets the number of spaces that are considered equal to a
tab character
Saves the changes to the file before running
Create region Creates a new region surrounding the selected text
Comment selection Comments out the selected text
Convert to space indenting Converts all tab characters in the script to spaces. The num-
ber of spaces is determined by Tab size
Convert to tab indenting Converts all x number of space characters (determined by
Tab size) in the script to tabs
DR

Python (documentation) Opens a link to the python website, showing you the python
syntax and standard libraries

6.4.8 Shortcuts
The shortcut keys of the scripting editor within the User Interface are documented in Table 6.2.

Table 6.2: Shortcut keys within the scripting editor of the User Interface.

Shortcut Function

Ctrl + Enter Run selection (or entire script with no selection)

Ctrl + Shift + Run current region (region where the cursor is in)
Enter
Ctrl + X Cut selection
Ctrl + C Copy selection
Ctrl + V Paste selection
Ctrl + S Save script
Ctrl + - Collapse all regions
Ctrl + + Expand all regions
Ctrl + " Comment or Uncomment current selection
Ctrl + W Add selection as watch variable
Ctrl + H Highlight current selection in script (press esc to cancel)
F9 Add/remove breakpoint (In debug mode only)

Deltares 61 of 562
 Getting started with Graphical User Interface

Table 6.2: Shortcut keys within the scripting editor of the User Interface.

Shortcut Function

F5 Continue running (In debug mode only — when on break-

point)
Shift + F5 Stop running (In debug mode only — when on breakpoint)
F10 Step over current line and break on next line (In debug mode
only - when on breakpoint)

T
F11 Step into current line if possible, otherwise go to next line
(In debug mode only — when on breakpoint). This is used
to debug functions declared in the same script (that have
already runned)
AF
6.4.9 Quick access toolbar
Note: The user can make frequently used functions available by a single mouse-click in the
Quick Access Toolbar, the top-most part of the application-window. Do this by right-mouse-
clicking a ribbon item and selecting Add to Quick Access Toolbar.
DR

Figure 6.20: The quick access toolbar.

6.5 Important differences compared to Delft3D-FLOW GUI

The differences between the former Delft3D-FLOW GUI and the D-Flow FM GUI in lay-out
and functionality are numerous. Here, we address only the most important differences in the
workflow.

6.5.1 Project vs model

The entity “project” is new in the D-Flow FM GUI. In the hierarchy the entity “project” is on a
higher level than the entity “model”. A project can contain multiple models, which can either
run standalone or coupled. The user can run all models in the project at once (on project level)
or each model separately (on model level). When the user saves the project, the project set-
tings will be saved in a <∗.dsproj> configuration file and the project data in a <*.dsproj_data
folder>. The <*.dsproj_data> folder contains folders with all input and output files for the
models within the project. There is no model intelligence in the <∗.dsproj> configuration file,
meaning that the models can also be run outside the GUI from the <*.dsproj_data> folder.

Deltares 62 of 562
 Getting started with Graphical User Interface

6.5.2 Load/save vs import/export

The user can load an existing D-Flow FM project, make changes in the GUI and, consequently,
save all the project data. Loading and saving means working on the original project data, i.e.
the changes made by the user overwrite the original project data. Alternatively, use Save As
to keep the original project data and save the changes project data at another location (or with
another name).

Import/export functionality can be used to copy data from another location into the project
(import) or, vice versa, to copy data from the project to another location (export). Import/export

T
is literally copying, e.g.:

⋄ import: changes on the imported data will only affect the data in the project and not the
source data (upon saving the project)
⋄ export: the model data is copied to another location “as is”, changes made afterwards will
only affect the data in the project not the exported data (upon saving the project)
AF
6.5.3 Working from the map
One of the most important differences with the former GUI is the central map. The central
map is comparable with the former “visualization area”, but with much more functionality and
flexibility. The map helps you to see what you are doing and inspect the model at all times.
You can use the Region and Map ribbons to add/edit model features in the map.

6.5.4 Coordinate conversion

DR

With the map as a central feature, functionality to convert model and map coordinates is an
indispensable feature. In the General tab you can set the model coordinate system. In the
map tree you can set the map coordinate system using the right mouse button (Figure 6.21).
The coordinate systems are subdivided in geographic and projected systems. Use the quick
search bar to find the coordinate system you need either by name or EPSG code (Figure 6.22).

Figure 6.21: Set map coordinate system using right mouse button

Deltares 63 of 562
 Getting started with Graphical User Interface

T
AF
Figure 6.22: Select a coordinate system using the quick search bar

6.5.5 Model area

The model area contains geographical features, such as observation points & curves and
obstacles. In contrast to the former GUI, these features can even exist without a grid or outside
the grid and they are not based on grid coordinates, implying that their location remains the
DR

same when the grid is changed (for example by (de-)refining).

Finally, for the computations, the SWAN computational core interpolates the features to the
grid. In the future we would like to show to which grid points the features are snapped before
running the computation. However, this requires some updates in the SWAN computational
core.

6.5.6 Integrated models (model couplings)

The D-Flow FM User Interface implements the concept of an Integrated model in order to
couple different models, such as: hydrodynamics coupled with the controlling of structures,
waves, morphology and/or water quality.

Two types of coupling are distinguished:

1 offline coupling and
2 online coupling.

Note: Offline is also referred to as sequential coupling and online as parallel coupling.

Deltares 64 of 562
 Getting started with Graphical User Interface

Offline
In case of an Integrated model with offline coupling, the entire hydrodynamic simulation is
done first, i.e., separately from the second simulation. The file-based hydrodynamic output
serves as input for the second simulation. As such, the hydrodynamic results drives the
controlling of structures or the simulation of waves or water quality. In this offline case, there
is no feedback from the waves or water quality to the hydrodynamic simulation. For many
applications, this is good practice.

Online

T
An online coupling, on the other hand, exchanges data every time after computing a specified
time interval. This tight coupling allows for direct feedback of the various processes on one
AF another. This is crucial for controlling structures.

6.5.7 Ribbons (shortcut keys)

The User Interface makes use of ribbons, just like Microsoft Office. You can use these ribbons
for most of the operations. With the ribbons comes shortcut key functionality, providing short-
cuts to perform operations. If you press Alt, you will see the letters and numbers to access
the ribbons and the ribbon contents (i.e. operations). For example, Alt + H will lead you to
the Home-ribbon (Figure 6.23).

Note: Implementation of the shortcut key functionality is still work in progress.

DR

Figure 6.23: Perform operations using the shortcut keys

6.5.8 Context menus

Context menus are the menus that pop up using the right mouse button. These context menus
provide you with some handy functionality and shortcuts specific for the selected item. The
functionality is available in all User Interface windows and context dependent. You can best
try it yourself to explore the possibilities.

6.5.9 Scripting
The User Interface has a direct link with scripting in Iron Python (NB: this is not the same
as C-Python). This means that you can get and set data, views and model files by means
of scripting instead of having to do it all manually. Scripting can be a very powerful tool to
automate certain steps of your model setup or to add new functionality to the GUI. You can
add a new script by adding a new item, either in the Home-ribbon or through the right mouse
button.

Deltares 65 of 562
 7 Set-up of a D-Flow FM model

7.1 Introduction
In order to set up a hydrodynamic model you must prepare an input file. All parameters to
be used originate from the physical phenomena being modelled. Also from the numerical
techniques being used to solve the equations that describe these phenomena, and finally,
from decisions being made to control the simulation and to store its results. Within the range
of realistic values, it is likely that the solution is sensitive to the selected parameter values, so
a concise description of all parameters is required. This input data is collected into the Master

T
Definition Unstructured file, called a mdu-file.

In section 7.2 we discuss some general aspects of the mdu-file and its attribute files. The
sections thereafter describe how the actual modelling process can be done in the GUI.

7.2
AF mdu-file and attribute files
The Master Definition Unstructured file (mdu-file) is the input file for the hydrodynamic simu-
lation program. It contains all the necessary data required for defining a model and running
the simulation program. In the mdu-file you can define attribute files in which relevant data
(for some parameters) is stored. This will be particularly the case when parameters contain
a large number of data (e.g., time-dependent or space varying data). The mdu-file and all
possible user-definable attribute files are listed and described in Appendix A.

Although you are not supposed to work directly on the mdu-file it is useful to have some ideas
on it as it reflects the idea of the designer on how to handle large amounts of input data and
DR

it might help you to gain a better idea on how to work with this file.

The basic characteristics of an mdu-file are:

⋄ It is an ASCII file.
⋄ Each line contains a maximum of 256 characters.
⋄ Each (set of) input parameter(s) is preceded by a (set of) keyword(s).

The results of all modules are written to platform independent binary (netCDF-)files, so also
these result files you can transfer across hardware platforms without any conversion.

The mdu-file contains several sections, denoted by square brackets, below are the most rele-
vant ones:
[general] this section contains the program name and its version.
[geometry] in this section, the main entry comprises the specification of the grid (i.e.
the netCDF network file). In addition, thin dams and thin dykes can be specified.
[numerics] this section contains the settings of specific parts of the flow solver, such
as limiters and the iterative solver type.
[physics] in this field, physical model parameters can be inserted, for instance related
to friction modelling and turbulence modelling.
[wind] the wind section prescribed the dependency of the wind drag coefficient to the
wind velocity through 2 or 3 breakpoints. This field also contains pressure infor-
mation.
[time] in this section, the start time and the stop time of the simulation are specified
(both as a combination of a date and time).
[restart] in this section, the restart file can be specified, either as a <∗_map.nc>-file
or as an <∗_rst.nc> file. Because a <∗_map.nc>-file can contain multiple

Deltares 66 of 562
 Set-up of a D-Flow FM model

stages, in this case also a RestartDateTime must be specified.

[external forcing] this section only contains the name of the external forcings file.
[output] in this section, the writing frequency of output data can be prescribed.

Appendix A contains the full list of MDU sections and keywords.

7.3 Filenames and conventions

Filenames and file extensions hardly have any strict requirements in D-Flow FM, but we do
advise to use the suggested file naming patterns below:

T
file pattern description

mdu_name.mdu mdu-file
∗_net.nc
AF ∗.xyz
∗.ldb
Unstructured grid (network) file
Sample file (for spatial fields)
Land boundary file (polyline file format)
∗_thd.pli Thin dam file (polyline file format)
∗_fxw.pliz Fixed weir file (polyline file format with z values)
∗_part.pol Partitioning polygon file (polyline file format)
∗.ext External forcings file
pli_name.pli Boundary condition location file (polyline file format)
DR

pli_name_000X.tim Timeseries boundary data file at point #X

pli_name_000X.cmp Astronomic/harmonical component boundary data file at point #X
∗.bc BC-format boundary data file with polyline and point labels in file
∗.xyn or ∗_obs.ini Observation station file (see section F.2.2)
∗_crs.pli or ∗_crs.ini Observation cross-sections file (see section F.2.4)
mdu_name_map.nc Output map file
mdu_name_his.nc Output his file
mdu_name_clm.nc Output class map file (see section F.3.3)
mdu_name.dia Output diagnostics (log) file

7.4 How to set-up a D-Flow FM model

This chapter describes how to set up a D-Flow FM model in an empty User Interface project.
When you open the GUI, an empty project is automatically created. Starting from scratch, you
have to create an empty D-Flow FM model in a User Interface project:
⋄ In the ribbon menu items, go to Home and click on New Model. In the drop-down menu
Figure 7.1 that appears, select "Flow Flexible Mesh Model" to add an empty D-Flow FM
model.
⋄ Or use the right mouse button on the name of your project (project1 by default). In the
context menu that appears Figure 7.2, select Add and click New Model. The Select model
... window appears allowing you to add an empty D-Flow FM model.

Deltares 67 of 562
 Set-up of a D-Flow FM model

Figure 7.1: The Add Model drop-down menu

T
AF
Figure 7.2: The Select model ... window

In the Project window, an empty model has appeared (FlowFM by default). Click the plus
sign (+) before the name of the model to expand all model attributes in the Project window:
DR

General, Area, Grid, Bed Level, Time Frame, Processes, Initial Conditions, Boundary Con-
ditions, Physical Parameters, Sources and Sinks, Numerical Parameters, Output Parameters
and Output. In the following paragraphs, all model attributes are treated separately.

7.4.1 General
When you double click on General in the Project window, the tabbed editor for the D-Flow FM
appears (Figure 7.3). The general tab contains general model information such as the model
coordinate system and the angle of latitude and of longitude.

Figure 7.3: Overview of general tab

7.4.1.1 Model coordinate system

A very important property of your model is the coordinate system in which it is specified.
Within the interface, there is a clear distinction between the coordinate system of your model
and all of its attributes and the coordinate system of the central map and all of its items. Both
coordinate systems can be set independent from each other. Keep in mind, that the coordinate
system of your model is saved and used when you run your model. Only coordinate systems
supported by the computational core are supported.

Deltares 68 of 562
 Set-up of a D-Flow FM model

The model coordinate system can be set using the globe icon next to the Coordinate system
text box. After clicking this button, the coordinate system wizard is opened (Figure 7.4). This
wizard allows you to choose one of many possible coordinate systems and apply it to your
model. You can use the search bar to browse the various coordinate systems (searching
possible by name and EPSG code). If your model is specified in a certain coordinate system
already, it is possible to convert the model coordinate system using the same button. After
clicking OK, all model attributes are converted to the system of choice. Note that you have to
close and re-open all map views for the changes to take effect in these views.

T
AF
DR

Figure 7.4: Coordinate system wizard

The map coordinate system applies to all items in the map Project window. To change the
map coordinate system, navigate the menu ribbons to Map and click on Map coordinate sys-
tem. Alternatively, right mouse click on Map in the map Project window and select Change
Map Coordinate System. The coordinate system wizard appears, allowing you to set the map
coordinate system of your choice. When the original model coordinate system differs from the
selected map coordinate system, all map items are automatically converted to the specified
map coordinate system.

7.4.1.2 Angle of latitude

For a Cartesian grid you have to specify the latitude of the model area; this is used to calculate
a fixed Coriolis force for the entire area. For a spherical grid the Coriolis force is calculated
from the latitude coordinates in the grid file and thus varies in the latitude direction. Typically,
you use spherical co-ordinates for large areas, such as a regional model. When a value of 0
is entered, the Coriolis force is not taken into account.

Deltares 69 of 562
 Set-up of a D-Flow FM model

7.4.2 Area
The model area contains all geographical features, such as the observation points, structures
and land boundaries. These features can exist without a grid or outside the grid as they are not
based on grid coordinates but xy -coordinates. This means that the location of the model area
features remains the same when the grid is changed (for example by (de-)refining). When
you expand the model attribute Area in the Project window, a list of supported geographical
features is displayed (Figure 7.5).

T
AF
DR

Figure 7.5: Overview of geographical features

Below is Figure 7.6. It displays an overview of the (Map) ribbon.

The red boxes to the left (FM Region 2D / 3D) and right (Area) can be used to Add ... the
various geographical features to the model: click the corresponding item in the box and use
your mouse to indicate the location of the selected feature on the central map. The red box in
the middle highlights the buttons available to edit the location of geographical features. The
specifics for each feature are discussed separately in the following sections.

Figure 7.6: Overview of Map ribbon

Importing and exporting of model features is done with the context menu by using your right
mouse button on the different features in the Project window.

7.4.2.1 Grid-snapped features

All geographical features of your model that are described by x-, and y -coordinates have
to be interpolated to your computational grid when you run your model. The computational
core of D-Flow FM automatically assigns these features to the corresponding parts of your

Deltares 70 of 562
 Set-up of a D-Flow FM model

grid. The so-called Grid-snapped features are part of the output of a simulation: shape files.
In section 7.4.14 is described how - in short: select Write Snapped Features in the Output
Parameters tab below the central map.

However, the graphical user interface allows you to inspect the grid-snapped features before
a simulation run.
Note: Mark that this way, the grid-snapping is an estimation because it would take too much
processing time. In the neighbourhood of Dry Areas the grid-snapping will be different, as
the Dry Areas are not taken into account in this interactive Estimated Grid-snapped features
mode.

T
AF
DR

Figure 7.7: Example of expanded Estimated Grid-snapped features attribute in the Map
window

Figure 7.7 shows a part of the Map window, showing the Area and Estimated Grid-snapped
features attributes. The x- and y -locations of all spatial model features are shown within the
Area attribute. You can hide or show any of these attributes by means of clicking the check
boxes in front of the attributes. When you enable the Grid-snapped features, all items within
the Area attribute, as well as all boundaries are interpolated to their corresponding locations
on the computational grid. The interpolation is performed instantaneously by the computa-
tional core of D-Flow FM, which enables you to directly inspect the numerical interpretation of

Deltares 71 of 562
 Set-up of a D-Flow FM model

all features on the computational grid. Figure 7.8 shows an example of four observation points
and one thin dam in the central map, showing both the x- and y -locations of these features
as well as their representation on the computational grid.

T
AF Figure 7.8: Example of grid snapped features displayed on the central map

7.4.2.2 Observation points

Observation points are used to monitor the time-dependent behaviour of one or all computed
quantities as a function of time at a specific location, i.e., water level, velocity, salinity, tem-
perature and concentration of the constituents. Observation points represent an Eulerian
viewpoint at the results.

To add an observation point, click the corresponding icon from the FM Region 2D / 3D menu
in the map ribbon (Figure 7.6). By clicking in the central map, observation points are placed
in your model. Selected observation points (first click the Select icon from the “Tools” menu
in the map ribbon) can be deleted using backspace or directly from the attribute table (ex-
DR

plained below). The grid snapped representation (Figure 7.9) is indicated by a line linking the
observation points to the closest cell center, indicating that output will be stored of this cell.
Importing and exporting of observation points is possible via the context menu of “Observation
points” in the Project window (right mouse button).

Figure 7.9: Geographical and grid snapped representation of an observation point

When you double click the Observation points attribute in the Project window, the observation
points tab is displayed underneath the central map (Figure 7.10). This tab shows an attribute
table with the names, x- and y -locations (in the model coordinate system) of the various
observation points within the model. When one of the entries is selected, the corresponding
observation point is highlighted in the central map.

Deltares 72 of 562
 Set-up of a D-Flow FM model

T
Figure 7.10: Attribute table with observation points

7.4.2.3 Observation cross-sections

Cross-sections (Figure 7.11) are used to store the sum of computed fluxes (hydrodynamic),
AF flux rates (hydrodynamic), fluxes of matter (if existing) and transport rates of matter (if existing)
sequentially in time at a prescribed interval.

To add a cross section, click the corresponding icon from the FM Region 2D / 3D menu in
the map ribbon (Figure 7.6). By clicking in the central map, cross section points are added.
Note that a cross section consists of a minimum of two points, but an arbitrary amount of
intermediate points can be added. The last point is indicated by double clicking the left mouse
button. The distance in meters (independent of the local coordinate system) in between the
last point and the mouse pointer is indicated in pink; in case more than two points are used,
the cumulative length of the entire cross section is shown in black. Once highlighted in the
central map, a cross section is deleted with backspace or directly from the attribute table
DR

described below. The positive direction through the cross section is indicated by a pink arrow.
The direction of this arrow is dependent on the order in which the cross section points are
drawn (to change the direction, flip the start and end points). Importing and exporting of
cross sections is possible via the context menu of “Observation cross-sections” in the Project
window (right mouse button).

Figure 7.11: Geographical and grid snapped representation of a cross section

Double clicking the Observation cross-sections attribute in the Project window enables the
Observation cross-sections tab underneath the central map view (Figure 7.12). Alternatively,
you can double click on any cross section in the map. The attribute table displayed in the tab
contains the names of the various cross sections of your model. When one of the entries is
selected, the corresponding cross section is highlighted in the central map. A cross section
entry can be deleted from the table via the context menu (right mouse button).

Deltares 73 of 562
 Set-up of a D-Flow FM model

Figure 7.12: Attribute table with observation cross sections

T
7.4.2.4 Thin dams
Thin dams (Figure 7.13) are infinitely thin objects defined at the velocity points which prohibit
flow exchange between the two adjacent computational cells without reducing the total wet
AF surface and the volume of the model. The purpose of a thin dam is to represent small obsta-
cles (e.g. breakwaters, dams) in the model which have sub-grid dimensions, but large enough
to influence the local flow pattern. A thin dam is assumed to have an infinite level in the model;
no water will ever overflow a thin dam.

To add a thin dam, click the corresponding icon from the FM Region 2D / 3D menu in the map
ribbon (Figure 7.6). Adding, deleting, importing and exporting of a line feature such as a thin
dam is discussed in more detail in section 7.4.2.3 on cross sections.
DR

Figure 7.13: Geographical and grid snapped representation of a thin dam

When you double click the Thin dams attribute in the Project window, the corresponding Thin
dams tab appears underneath the central map (Figure 7.14). Alternatively, you can also
double click on any thin dam in the central map. Within this tab, an attribute table is shown
which displays the names of all thin dams within your model. When one of the entries is
selected, the corresponding item is highlighted in the central map. A thin dam entry can be
deleted from the table via the context menu (right mouse button).

Deltares 74 of 562
 Set-up of a D-Flow FM model

T
AF Figure 7.14: Attribute table with thin dams

7.4.2.5 Fixed weirs

A fixed weir (Figure 7.15) has the same function as a thin dam (section 7.4.2.4). However,
unlike a thin dam, a fixed weir can be assigned both xy - and z -values. Furthermore, a fixed
weir can be assigned a crest length (a thin dam is infinitely thin). The z -values correspond
to the crest level of the fixed weir at the corresponding x- and y -locations; the level can vary
in space, but is constant in time (Figure 7.16). Consequently, a fixed weir can overflow if the
water level exceeds the crest level of the fixed weir. The level is specified with regard to the
same vertical reference level as all other model items with level specifications (e.g. bed level
values and initial water levels).
DR

Figure 7.15: Geographical and grid snapped representation of a fixed weir

Figure 7.16: Schematic representation of a fixed weir

To add a fixed weir, click the corresponding icon from the FM Region 2D / 3D menu in the
map ribbon (Figure 7.6). Adding, deleting, importing and exporting of a line feature such as a
fixed weir is discussed in more detail in section 7.4.2.3 on cross sections.

When you double click the Fixed weirs attribute in the Project window, the corresponding
Fixed weirs tab appears underneath the central map (Figure 7.17). Alternatively, you can also

Deltares 75 of 562
 Set-up of a D-Flow FM model

double click on any fixed weir in the central map. Within this tab, an attribute table is shown
which displays the names of all fixed weirs within your model. When one of the entries is
selected, the corresponding item is highlighted in the central map. A fixed weir entry can be
deleted from the table via the context menu (right mouse button).

T
AF Figure 7.17: Attribute table with fixed weirs

When you double click on a fixed weir in the central map, the fixed weir editor opens in a
separate view (Figure 7.18). On the right, a graphic representation (top view) of the fixed weir
is displayed. The support point that is selected in the table is highlighted by means of a blue
circle. On the left, a table is displayed showing the following properties of each support point
of the fixed weir under consideration:

⋄ X: x-coordinate of support point

⋄ Y: y -coordinate of support point
⋄ Crest level: crest level of the support point of support point of a fixed weir
⋄ Ground height left: Difference between crest level and toe level at the left side
DR

⋄ Ground height right: Difference between crest level and toe level at the right side
⋄ Crest width: Width of the crest of a fixed weir in perpendicular direction
⋄ Slope left: Slope at left side of support point of a fixed weir
⋄ Slope Right: Slope at right side at support point of support point of a fixed weir
⋄ Roughness code: Roughness due to vegetation on a support point of a fixed weir

Figure 7.18: Fixed weir editor

Deltares 76 of 562
 Set-up of a D-Flow FM model

7.4.2.6 Land boundaries

A land boundary (Figure 7.19) encloses the main geographic features surrounding your model
and indicates the intersection of the water and land masses. When you set up your computa-
tional grid in RGFGRID, a land boundary determines the onshore extent of your model. When
you open RGFGRID to edit your grid, the land boundary is automatically transferred and dis-
played. For more details on grid generation, you are referred to the User Manual of RGFGRID
(Deltares, 2025l).

T
AF
Figure 7.19: Geographical representation of a land boundary

To add a land boundary, click the corresponding icon from the FM Region 2D / 3D menu in
the map ribbon (Figure 7.6). Adding, deleting, importing and exporting of a line feature such
as a land boundary is discussed in more detail in section 7.4.2.3 on cross sections.
DR

When you double click the Land boundaries attribute in the Project window, the corresponding
land boundaries tab appears underneath the central map (Figure 7.20). Alternatively, you can
also double click on any land boundary in the central map. Within this tab, an attribute table is
shown which displays the names of all land boundaries within your model. When one of the
entries is selected, the corresponding item is highlighted in the central map. A land boundary
entry can be deleted from the table via the context menu (right mouse button).

Figure 7.20: Attribute table with land boundaries

Deltares 77 of 562
 Set-up of a D-Flow FM model

7.4.2.7 Dry points and Dry areas

Dry points are grid cells centred around a water level point that are permanently dry during
a computation, irrespective of the local water depth and without changing the water depth as
seen from the wet points. Dry areas are the same, but provide an easy way of defining many
grid points as a single dry area at once.

Note that the flexibility of unstructured grids makes the use of dry points less necessary than
with structured grid models, such as Delft3D-FLOW. In the interior of unstructured grids, some
or more grid cells can easily be deleted during grid manipulation. Still, a dry points file can be

T
used to explicitly mark locations or regions inside the grid as dry cells.

Dry points in the GUI

AF
DR

Figure 7.21: Geographical and grid snapped representation of several dry points

To add a dry point, click the corresponding icon from the FM Region 2D / 3D menu in the map
ribbon (Figure 7.6). Adding, deleting, importing and exporting of a point feature such as a dry
point is discussed in more detail in section 7.4.2.2 on observation points. The grid snapped
representation of a dry point (Figure 7.21) is indicated by a line linking the dry point to the
closest cell center.

When you double click the “Dry points” attribute in the Project window, the corresponding
Dry points tab appears underneath the central map (Figure 7.22). Alternatively, you can also
double click on any dry point in the central map. Within this tab, an attribute table is shown
which displays the names of all dry points within your model. When one of the entries is
selected, the corresponding item is highlighted in the central map. A dry point entry can be
deleted from the table via the context menu (right mouse button).

Deltares 78 of 562
 Set-up of a D-Flow FM model

T
Figure 7.22: Attribute table with dry points
AF
Dry areas in the GUI
Dry areas (Figure 7.23), like dry points, indicate areas that permanently dry during a com-
putation. Instead of adding many separate dry points, you can draw a polygon that encloses
all required computational cells. Only cells which centers are strictly inside the polygon are
taken into account. The grid snapped representation of the dry area clearly indicates which
cells are considered within the dry area.
DR

Figure 7.23: Geographical and grid snapped representation of a dry area

When you double click the Dry areas attribute in the Project window, the corresponding Dry
areas tab appears underneath the central map (Figure 7.24). Alternatively, you can also
double click on any dry area in the central map. Within this tab, an attribute table is shown
which displays the names of all dry areas within your model. When one of the entries is
selected, the corresponding item is highlighted in the central map. A dry area entry can be
deleted from the table via the context menu (right mouse button).

Deltares 79 of 562
 Set-up of a D-Flow FM model

T
Figure 7.24: Attribute table with dry areas

Dry points file input

AF Dry points are defined by a sample file <∗.xyz>, dry areas are defined by a polygon file
<∗.pol>. Add the filename to the MDU as below:

[geometry]
# ...
DryPointsFile = <filename.xyz> # Dry points file *.xyz, third column dummy z values,
# or polygon file *.pol.

The format of the sample file is defined in section C.3. The format of the polygon file is defined
in section C.2. All grid cells that contain a sample point are removed from the model grid, and
as a result do not appear in any of the output files. Alternatively, for a polygon file, all grid cells
DR

whose mass center lies within the polygon will be removed from the model grid.

7.4.2.8 Pumps
Pumps are a type of structures in D-Flow FM. Unlike the other structures, pumps can force the
flow only on one direction. This direction is determined by arrow in D-Flow FM. The direction
of pump can be reverted by mouse right-click and selecting "Reverse line(s)".

Like all other structures in D-Flow FM, the pump can be defined by a polygon. The input data
of the pumps can be given by selecting and editing the pump polygon (see Figure 7.25). Right
click on the pump polygon and selecting "Delete Selection" leads to deletion of the selected
pump. Double clicking the pump polygons (or right click the pump in the list and select "Open
view"), it opens a tab for editing the pump properties. The tab includes pump capacity. If the
pump capacity is time dependent, it can be given by time series data (Figure 7.25).

Figure 7.25: Polygon for pump (a) and adjustment of physical properties (b).

Right clicking the pumps attribute in the Project window opens a pop-down window on which

Deltares 80 of 562
 Set-up of a D-Flow FM model

you can select to import or export pumps. The pumps can be imported as polyline by a
<∗.pli> file or by a structure file, and they can be exported as a <∗.pli> file, structure file, or
<shapefile>.

Double clicking the pumps attribute in the Project window opens the pumps tab underneath
the central map. The attribute table in this tab shows all pumps with their corresponding
properties. When one of the pumps is selected, the corresponding item is highlighted in
the central map. Double clicking any of the pumps in the central map opens the Structure
Editor underneath the central map in which all parameters related to the pump can be set
(Figure 7.26).

T
AF
Figure 7.26: Selection of the pumps

7.4.2.9 Weirs
DR

Unlike the fixed weir, weir (or adjustable weir) can be adjusted based on the user require-
ments. To set an adjustable weir in the computational domain, you can select the icon Add
new structure (2D) from the toolbar, and draw a line by mouse. This line includes direction,
which defines the sign of total flux passing above the structure (positive flux in the direction
of weir, otherwise negative). This direction can be inverted by mouse right-click and selecting
Reverse line(s). By double-click on the line, you can define this structure as Simple weir and
add the geometrical and time-dependent parameters such as Crest level, Crest width, Crest
level time series and Lateral concentration coefficient (See Figure 7.27).

Figure 7.27: Polygon for adjustable weir (a) and adjustment of geometrical and temporal
conditions (b).

Moreover, the time series of the crest level can be set in the case the crest level is time
dependent. The time dependency diagram can be defined by the help of time series diagram

Deltares 81 of 562
 Set-up of a D-Flow FM model

as shown in Figure 7.28. The time series can also be imported (and exported) from external
<csv>-file.

T
AF Figure 7.28: Time series for crest level.

The weirs can be deleted, imported and exported. By right clicking on the weir polygon, and
selecting "Delete Selection" from the pop-down window, you can delete the selected weir.
Right clicking the "Weirs" attribute in the Project window opens the "Weirs" tab opens the
options for import and export. You can import weirs as polygon (<∗.pli> file) or as a structure
by structure file. The weirs can also be exported to a polygon file, to a structure data file, or
by the help of a shape file.
DR

Double clicking the "Weirs" attribute in the Project window opens the "Weirs" tab underneath
the central map. The attribute table in this tab shows all weirs with their corresponding prop-
erties. When one of the weirs is selected, the corresponding item is highlighted in the central
map. Double clicking any of the weirs in the central map opens the Structure Editor as a new
map view in which all parameters related to the weir can be set (Figure 7.29).

Figure 7.29: Time series for crest level.

7.4.2.10 Gates
In D-Flow FM the gates can be imposed by polygon, and can be edited in a similar way as the
other structures (see Figure 7.30). Like the other structures, mentioned above, the gates can
be imported and exported by means of structure file or <∗.pli> file.

Deltares 82 of 562
 Set-up of a D-Flow FM model

Figure 7.30 shows the edit tab of the gate properties. The gate can be opened horizontally,
as well as vertically.

T
AF
Figure 7.30: Polygon for gate (a) and adjustment of geometrical and temporal conditions
(b).

7.4.2.11 Bridge Pillars

Remark:
⋄ Bridge pillar functionality is currently only available for 1D and 2D modelling, but not for
DR

3D modelling yet.

Bridge pillars are a type of structures in D-Flow FM that are relevant for the hydrodynamics.
In D-Flow FM, a bridge is defined by a polygon on the central map. The user can add a bridge
to the model by

⋄ selecting the Add new bridge pillar icon in the Map ribbon; and
⋄ defining the location of the bridge pillars by clicking on the map. The polyline for a bridge
is finalized by double-clicking on the last bridge pillar.)
⋄ repeat the above for another bridge and end by pressing the <ESC> key

Figure 7.31: Selection of a bridge

Right clicking on the bridge polygon and selecting Delete Selection leads to deletion of the

Deltares 83 of 562
 Set-up of a D-Flow FM model

selected bridge. After double clicking a bridge polygon or right clicking the bridge in the list
and selecting Open view, a tab for editing the bridge properties opens (Figure 7.32), with the
following parameters:

⋄ Pillar diameter [m] - (use -999.0 for an auxiliary location)

⋄ Drag coefficient [-]: default is 1.0

T
AF Figure 7.32: Adjustment of the properties of the pillars

Right clicking the Bridge Pillars attribute in the Project window (Figure 7.31) opens a pop-
down window on which you can select to import or export bridges. The bridges can be im-
ported and exported as polyline by a <∗.pliz> file or <shapefile>.

As can be seen in Figure 7.32, some of the points of the polygon are relevant pillars with real
dimensions and some are not. For example, if a bridge is of curved shape, then additional
points can be used to visualize such a bridge, while some of the points of a polyline do not
DR

coincide with a pillar. Such points are modelled with a pillar diameter of -999.0.

7.4.3 Computational grid

To set up a grid, click on the Edit grid button which opens the program RGFGRID. All features
of grid setup in RGFGRID are treated separately in Deltares (2025l). If a land boundary is
present in your project, this is exported to RGFGRID automatically. Once you have setup
your grid in RGFGRID, click File →Save Project and close the program. The grid will now be
visible within the central map. Editing of the grid remains possible at any point in time during
the setup of your model by means of clicking the edit grid button. Any changes you make are
always saved after clicking File →Save Project and loaded back into the central map.

7.4.4 Bed level

When you double click on Bed level in the Project window or select Bed level from the drop-
down box in the spatial editor section of the Map ribbon, the spatial editor is activated (Fig-
ure 7.33). This editor can be used to generate a bathymetry for your computational grid. How
to work with the spatial editor is described in Appendix H. Be aware that the bathymetry in
D-Flow FM is defined as the bed level (e.g. positive upward), implying that all bed levels below
the reference plane are negative. By default the bed levels are defined on the net nodes.

Note: Please note that, currently, other bed level definition types (e.g. BedlevTypes) are
not visually supported by the GUI. If you would like to switch the bed level defintions to another
type, you have to set the BedlevType in the Physical Parameters tab. However, the bed
level locations will not be updated accordingly in the central map.

Deltares 84 of 562
 Set-up of a D-Flow FM model

T
Figure 7.33: Bed level activated in the spatial editor
AF
7.4.5 Time frame
In the settings tab, in the sub-tab time frame (Figure 7.34), you can specify everything related
to the time frame in which your model will run.
DR

Figure 7.34: Overview time frame tab

In general, the time frame is defined by a reference date and a start and stop time. The
time step size of your model is automatically limited (every time step) based on a Courant
condition. In more detail, you must define the following input data:
Max Courant nr The maximum allowed Courant number, which is used to compute
the time step size from the CFL criterium. D-Flow FM uses an ex-
plicit advection scheme, therefore a value of 0.7 or lower is advised.
Remark:
⋄ You should check the influence of the time step on your results
at least once.
Reference date The reference date of the simulation, which is by definition always at
midnight (00h00m00s). It defines the (arbitrary) t = 0 point for all
time-series as used in the simulation. In the GUI, time-specifications
are always absolute, but in the underlying model input files, these
are stored as time values relative to the reference date. Typically,
input time-series files are specified in minutes after this t = 0 point.
See for an illustration Figure 7.35.
Time zone The time difference between local time and UTC.
The time zone is defined as the time difference (in hours) between
the local time (normally used as the time frame for D-Flow FM) and

Deltares 85 of 562
 Set-up of a D-Flow FM model

Reference Date Start Time Stop Time

Time

Figure 7.35: Relation between Reference Date and the simulation start and stop time
for astronomic- and harmonic-series as used in the simulation. Time-series

T
should cover the simulation time.

Coordinated Universal Time (UTC). The time difference can consist

of a part of an hour, for example 1 hour and 30 minutes (specify as
AF a decimal value: 1.5 (hours)). The local Time Zone is used for two
processes:
⋄ To determine the phases in local time of the tidal components
when tide generating forces are included in the simulation, see
section 3.7.
⋄ To compare the local time of the simulation with the times at
which meteo input is specified, e.g., wind velocities and atmo-
spheric pressure. These can be specified in a different time zone.
If the Time Zone = 0 then the simulation time frame will refer to UTC.
User time step The interval that is highest in the hierarchy. It specifies the inter-
DR

val with which the meteorological forcings are updated. The Max.
time step cannot be larger than the User time step, and it will auto-
matically be set back if it is. Also, the output intervals should be a
multiple of this User time step, see Appendix F. Finally the compu-
tational time steps will be fitted to end up exactly at each User time
step, such that proper equidistant output time series are produced.
Nodal update interval When using astronomic boundary conditions, the nodal factors can
be updated with certain intervals, see section 3.7.
Max. time step The Max. time step is the upper limit for the computational time
step. The automatic time step can not be switched off explicitly.
(If you want to enforce a fixed time step anyway, set the parame-
ter Max. time step (s) to the desired step size, and the parameter
Max. Courant nr. to an arbitrary high value.)
Initial time step the initial time step of the model; there is no data available yet during
the first time step to compute the time step automatically based on
a Courant condition. The computational time step then gradually
increases from Initial time step to the CFL-number limited time step
(assuming that Initial time step is relatively small).
Start Time The start date and time of the simulation.
Stop Time The stop date and time of the simulation. Always make sure that the
model Stop Time is larger than the model Start Time to avoid errors
during your calculation.

Deltares 86 of 562
 Set-up of a D-Flow FM model

7.4.6 Processes
In the processes tab (Figure 7.36) you can specify which processes you want to incorporate
into your model. You can choose whether or not to include tidal forcing, salinity, temperature
and sediment/morphology by means of check boxes. In addition, you can specify which Wave
model you want to use. Note that when ticking the sediment/morphology check box, two tabs
for setting sediment and morphology parameters appear.

T
AF Figure 7.36: Overview processes tab

7.4.7 Initial conditions

When expanding the initial conditions in the Project window, all quantities requiring an initial
state are shown (Figure 7.37). The number of quantities depends on the activated physical
processes in the ‘Processes’ tab (see section 7.4.6). The initial conditions for each quantity
can be specified as a uniform value or as a coverage (e.g. a spatially varying field).
DR

The uniform values can edited in the ‘Initial Conditions’ tab, which opens upon double clicking
‘Initial Conditions’ in the Project window (Figure 7.38). In this tab you can also specify the
layer distribution for the initial condition specification in case of a 3 dimensional quantity (i.e.
salinity). Note: Please note that for 3 dimensional initial conditions currently only the option
‘top-bottom’ is supported.

In case of spatially varying initial conditions you can double click the quantity in the Project
window or select it from the drop-down box in the spatial editor section of the Special Oper-
ations ribbon (Figure 7.39). Then the spatial editor is activated, which you can use to edit
spatially varying fields. For more information on how to use the spatial editor you are referred
to Appendix H. In case of 3 dimensional initial conditions, you can select the layer from the
quantity dropdown box in the ‘Map’ ribbon (Figure 7.40).

Figure 7.37: Initial conditions in the Project window

Deltares 87 of 562
 Set-up of a D-Flow FM model

Figure 7.38: The ‘Initial Conditions’ tab where you can specify the uniform values and the
layer distributions of the active physical quantities.

T
AF
DR

Figure 7.39: Initial water levels activated in the spatial editor

Figure 7.40: Selecting 3 dimensional initial fields from the dropdown box in the ‘Map’
ribbon to edit them in the spatial editor

Instead of defining initial conditions from scratch you can also import fields from a previous
computation (using restart files). When you run a model using the D-Flow FM GUI which is
writing restart files, the restart states will appear in the “Output” folder in the Project window
(Figure 7.41). For a description of the specification of restart files, please refer to paragraph
section 7.4.14. To use a restart file as initial conditions, apply the right mouse button and
select “Use as initial state”. The file will now appear under “Initial Conditions” in the Project

Deltares 88 of 562
 Set-up of a D-Flow FM model

window (Figure 7.42). To activate the restart file utilize the right mouse button and select “Use
restart”. The file will no longer be grey, but is now highlighted in black. The model will now
restart from this file. Notice that the simulation still starts at the original User Start Time, rather
than the time of the restart file. (The restart file only provides initial conditions.)

T
Figure 7.41: Restart files in output states folder

AF Figure 7.42: Restart file in initial conditions attribute

7.4.8 Boundary conditions

Boundary conditions consist of a location specification (‘support points’) and a forcing for that
location.

Section 7.4.8.1 describes how support points can be specified in D-Flow FM User Interface.
DR

The boundary forcing can be specified in the boundary data editor.

Section 7.4.8.2 describes the functionality of the boundary data editor. Finally, section 7.4.8.4
describes how the user can get an overview of the boundary locations and forcing in the
attribute table.

7.4.8.1 Specification of boundary locations (support points)

In D-Flow FM the boundary locations are defined as ‘support points’ on a polyline (<∗.pli>).
The user can add a boundary polyline (<∗.pli>) in the central map by selecting the ‘Add
Boundary’ icon in ’FM Region 2D / 3D’ of the ‘Map’ ribbon (see Figure 7.43). The number of
individual mouse clicks determines the number of support points on the polyline. The polyline
is closed by a double click. Once the polyline is added it becomes visible in the Project
window under ‘Boundary Conditions’ (see Figure 7.44). The polyline can be edited by the
general edit operations in the ‘Map’ ribbon (i.e. add/delete/move individual geometry points
or the complete geometry, see Figure 7.45). The name of the polyline (or ‘boundary’) can be
edited in the Boundaries tab, which can be opened by double clicking ‘Boundaries’ in the Map
window (see Figure 7.46).

Deltares 89 of 562
 Set-up of a D-Flow FM model

T
Figure 7.43: Adding a boundary support point on a polyline in the central map. By double
AF clicking on the polyline in the map, the boundary condition editor will open to
edit the forcing data on the polyline.
DR

Figure 7.44: Polyline added in Project window under ‘Boundary Conditions’. By double
clicking on the name of the polyline, the boundary condition editor will open
to edit the forcing data on the polyline.

Figure 7.45: Geometry edit options in Map ribbon

Deltares 90 of 562
 Set-up of a D-Flow FM model

T
AF
Figure 7.46: Edit name of polyline/boundary in Boundaries tab

7.4.8.2 Boundary data editor (forcing)

DR

The boundary condition editor can be opened either by double clicking on the boundary name
in the Project window (Figure 7.44) or by double clicking the boundary polyline in the map win-
dow (Figure 7.43). An overview of the boundary data editor is given in Figure 7.47. This editor
can be used to specify the boundary forcing for different quantities (i.e. water level, velocity,
discharge, salinity, etc.) corresponding to different processes (i.e. flow, salinity, temperature,
tracers). The user can select the processes and quantities in the upper left corner. In the
upper centre panel the user can select the forcing function for the selected quantity (i.e. time
series, harmonic components, astronomical components or Q-h relation). The upper right
corner contains a list of the support points on the polyline. The geometry view shows the
location of the selected support point on the polyline (<∗.pli>). In the middle panel are some
handy buttons to generate, import and export forcing data. In the lower left panel the user
can specify the boundary data for the selected support point. The lower right corner shows
the signal of the boundary data. The following sections describe the features of the boundary
data editor in more detail.

Deltares 91 of 562
 Set-up of a D-Flow FM model

T
AF
Figure 7.47: Overview of the boundary data editor

Process and quantity selection:

Currently, D-Flow FM supports the processes flow, salinity, temperature and tracers (Note:
tracers are not yet fully editable). The processes available in the boundary condition editor
depend on the selected processes in the processes tab (see section 7.4.6). After selecting
DR

the process from the dropdown box the user can select one of the corresponding quanti-
ties, as illustrated in Figure 7.48. For the process flow the user can choose from five principal
quantities: water level, velocity, Riemann invariant, Neuman gradient and discharge. All quan-
tities are specified per support point, except for discharges which are specified per polyline
(<∗.pli>). A support point can have multiple forcing quantities of the same type (i.e. water
level, velocity, Riemann, Neumann or discharge). These quantities are added up. This can be
relevant to add a surge level to an astronomical water level for example. Furthermore, the user
can apply normal and tangential velocities as ‘add on’ quantities. The following combinations
of quantities are allowed:

⋄ Water level + normal velocity

⋄ Water level + tangential velocity
⋄ Water level + normal velocity + tangential velocity
⋄ Velocity (= normal) + tangential velocity
⋄ Riemann + tangential velocity

Deltares 92 of 562
 Set-up of a D-Flow FM model

T
Figure 7.48: Process and quantity selection in the boundary data editor
AF
Forcing function selection:
The user can select one of the following forcing functions:

⋄ Time series
⋄ Harmonic components
⋄ Harmonic components + correction
⋄ Astronomic components
⋄ Astronomic components + correction
DR

⋄ Q-h relation (only for water levels)

The next section describes how data can be added for these types of forcing functions.

Add forcing data to a support point or polyline:

By default all support points on the polyline are deactivated. To add forcing data to a support
point the user first needs to activate it by pressing the green ‘add’-symbol in the list of support
points (see Figure 7.49). Consequently, the user can specify the forcing data in the lower left
panel based on the selected forcing function. Of which a preview is shown in the lower right
panel. Note: Please note that once a support point containing forcing data is made
inactive, all data on the support point is lost!

The user can choose from the forcing functions time series, harmonic components (+ correc-
tion), astronomic components (+ correction) and Q-h relation. Examples of the boundary data
specifications for these different forcing functions are given below. Note: Please note that
once the user changes the forcing function of a polyline, all data on the polyline is lost!

Deltares 93 of 562
 Set-up of a D-Flow FM model

T
Figure 7.49: Activate a support point
AF
Time series
Note: Time series have an attribute Time zone, as can be seen below.
DR

Figure 7.50: Time zone in the Boundary conditions editor

This attribute is un-editable, as it belongs to the data. The Time zone is defined as the time
difference between local time and UTC. By default the Time zone is 0. In case external
data is used, the Time zone can be different - as in Figure 7.50. The Time zone will be
used to transpose the (external) data to the Time zone of the time frame of the simulation
(see also section 7.4.5).

The time format for time series is yyyy-mm-dd HH:MM:SS.

There are multiple ways to specify time series for the selected quantity:

Deltares 94 of 562
 Set-up of a D-Flow FM model

⋄ Specify the time series step by step in the table (Figure 7.51): the user can add or delete
rows with the “plus”- and “minus”-signs below the table.

T
AF Figure 7.51: Specification of time series in the boundary data editor (left panel)

⋄ Generate time series using the ‘Generate time series’ button (Figure 7.52): the user can
specify start time, stop time and time step.
DR

Figure 7.52: Window for generating series of time points

⋄ Import from csv using the ‘Csv import’ button: a wizard will open in which the user can
(1) select a csv-file (Figure 7.53), (2) specify how data should be parsed into columns
(Figure 7.54) and (3) how the values should be parsed and mapped into columns (Fig-
ure 7.55).

Deltares 95 of 562
 Set-up of a D-Flow FM model

T
AF
DR

Figure 7.53: Csv import wizard: csv file selection

Deltares 96 of 562
 Set-up of a D-Flow FM model

T
AF
DR

Figure 7.54: Clipboard/csv import wizard: specification of how data should be parsed into
columns

Deltares 97 of 562
 Set-up of a D-Flow FM model

T
AF
DR

Figure 7.55: Clipboard/csv import wizard: specification of how values should be parsed
and columns should be mapped

⋄ Import from clipboard using the ‘Clipboard import’ button: a wizard will open in which the
user can specify (1) how data should be parsed into columns (Figure 7.54) and (2) how
the values should be parsed and mapped into columns (Figure 7.55).
⋄ Import from attribute file <∗.bc>: with this button the user can import data from existing
boundary conditions <∗.bc> file. The user has three options for importing:
Overwrite where matching (replace): only overwrites the forcing data for matching
⋄

support points in the <∗.bc>-file and GUI input.

Overwrite where missing (extend): only overwrites the forcing data for matching sup-
⋄

port points in the <∗.bc>-file and in the GUI input that did not contain data.
Overwrite all: overwrites the forcing data for all support points in the GUI (meaning
⋄

that the forcing data for non-matching support points is emptied).

Deltares 98 of 562
 Set-up of a D-Flow FM model

Harmonic components
The harmonic components are defined by a frequency, amplitude and phase (see Figure 7.56).
By default the forcing data viewer shows the harmonic component for the time frame specified
for the model simulation. The options to define the harmonic components are similar to the
options for time series:
⋄ Specify components step by step: the user can add or delete rows with the “plus”- and
“minus”-signs below the table.
⋄ Select (astronomical) components using the ‘Select components’ button (Figure 7.57): the
user can select astronomical components which will be transformed in the corresponding

T
frequencies.
⋄ Import from csv using the ‘Csv import’ button: a wizard will open in which the user can
(1) select a csv-file, (2) specify how data should be parsed into columns and (3) how the
values should be parsed and mapped into columns.
⋄ Import from clipboard using the ‘Clipboard import’ button: a wizard will open in which the
AF
user can specify (1) how data should be parsed into columns and (2) how the values
should be parsed and mapped into columns.
⋄ Import from attribute file <∗.bc>: with this button the user can import data from existing
boundary conditions <∗.bc> file. The user has three options for importing:
Overwrite where matching (replace): only overwrites the forcing data for matching
⋄

support points in the bc-file and GUI input.

Overwrite where missing (extend): only overwrites the forcing data for matching sup-
⋄

port points in the bc-file and in the GUI input that did not contain data.
Overwrite all: overwrites the forcing data for all support points in the GUI (meaning
⋄

that the forcing data for non-matching support points is emptied).

DR

Figure 7.56: Specification of harmonic components in boundary data editor

Deltares 99 of 562
 Set-up of a D-Flow FM model

T
AF
DR

Figure 7.57: Selection of astronomical components from list (after pressing ‘select com-
ponents’)

Astronomic components
Astronomical components are similar to harmonic components, with the exception that the
frequency is prescribed. Instead of specifying the frequency the user can select astronomical
components by name. Upon editing the component field in the table the user will get sugges-
tions for components in a list (Figure 7.58). The most frequently used components (A0, Q1,
P1, O1, K1, N2, M2, S2, K2 and M4) are put on top of the list, the other components are listed
in alphabetic order. Instead of defining each component individually, the user can also make
a selection of components by pressing the button ‘select components’ (Figure 7.57).

Deltares 100 of 562

 Set-up of a D-Flow FM model

T
AF Figure 7.58: Suggestions for astronomical components in list

Harmonic or astronomic components with corrections

For calibration purposes the user can combine harmonic or astronomic components with cor-
rections. The corrections are defined in terms of an amplitude (multiplication) factor and a
phase difference (see Figure 7.59). This allows the user to keep track of both the original sig-
nal and the calibration coefficients. The effects of the corrections on the resulting signal are
directly visualized in the forcing data viewer. Note: Please note that the import function-
ality is not (yet) working properly for astronomic/harmonic boundary conditions with
corrections.
DR

Figure 7.59: Editing harmonic/astronomic components and their corrections

Q-h relation (only for water level)

The user can force the boundary with a Q-h relationship, but only for the quantity water level.
This is a relationship between discharge and water level (see Figure 7.60). The relationship
can only be prescribed per polyline, not per support point. (Note: this functionality has not
been tested extensively yet)

Deltares 101 of 562

 Set-up of a D-Flow FM model

T
Figure 7.60: Specification of a Q-h relationship
AF Exporting boundary conditions
With the Export to files button the user can export all boundary forcing data for the given
polyline to a <∗.bc>-file.

7.4.8.2.1 3D boundary conditions

When the model is 3D (i.e. the number of layers is larger than 1), the user can specify three-
dimensional boundary conditions for relevant quantities such as velocity, salinity, temperature
DR

and tracer concentration. The user can choose from vertically uniform or vertically varying
boundary conditions (Figure 7.61), where the latter are defined as a percentage from the bed.
In the boundary condition editor the layer view will appear (Figure 7.62). Here, the user can
specify the vertical positions of the boundary conditions and view their position relative to
the model layers. Please note that the number and position of vertical boundary conditions
does not necessarily have to match the number and/or the exact position of the model layers.
The computational core will interpolate the boundary forcing position to the number of model
layers.

In case of non-uniform boundary conditions over the vertical, the number of columns in the
boundary forcing data editor will increase correspondingly (see Figure 7.63). In this way the
user can specify the conditions for all vertical positions in the same table and view the resulting
signals in the forcing data viewer.

Figure 7.61: Selection of vertically uniform or varying boundary conditions in case of a

3D model

Deltares 102 of 562

 Set-up of a D-Flow FM model

T
Figure 7.62: Overview of the layer view component of the boundary conditions editor. In
the table the user can edit the vertical positions of the boundary conditions
as a percentage from the bed. In the view left of the table, the user can
see the vertical positions of the boundary conditions (indicated by number
AF corresponding to the table) relative to the model layers.

Figure 7.63: Specification of boundary forcing data (in this example for salinity) at 3 posi-
tions in the vertical
DR

View boundary data

All boundary data of the same quantity on a support point can be (pre-)viewed in the boundary
data view in the lower-right panel. If multiple signals of the same process have been entered,
the viewer will show the active signal in red and the total signal of all datasets in green (see
Figure 7.64). In the view the user can zoom-in by dragging a box from top-left to bottom-right
and zoom-out by dragging a box from bottom-right to top-left.

Figure 7.64: Example of active and total signal for multiple water level data series on one
support point

To inspect multiple quantities at a support point at the same time (for example water level and
normal velocity) the user can use the combined boundary data viewer by pressing the button
‘Combined BC view’. Note: This does not work properly yet.

Deltares 103 of 562

 Set-up of a D-Flow FM model

7.4.8.3 Import/export boundary conditions from the Project window

Apart from import and export functionality per individual boundary polyline in the bound-
ary condition editor, the GUI offers the opportunity to import and export boundary locations
(<∗.pli>) and forcing (<∗.bc>) on a higher level. Hereto, you have to click the right mouse
button on “Boundary Conditions” in the Project window and select “Import” or “Export” (Fig-
ure 7.65). Imports and exports on “Boundary Conditions” apply to all the boundary conditions
whereas import and exports on a boundary polyline apply only to that boundary condition.

T
AF Figure 7.65: Importing or exporting boundary features — both polylines <∗.pli> and forc-
ing <∗.bc> — from the Project window using the right mouse button

Import and export polylines

Upon importing a <∗.pli>-file with the same filename and the same polyline name(s) as the
existing polyline names in the GUI, the existing polyline(s) will be replaced and all forcing data
thereon will be deleted. Upon importing a polyline(s) with a different name(s), the polyline(s)
will be added to the Project window without any forcing data on it/them. The user will be
DR

asked to import the data “as is” or to perform a coordinate transformation before the import
(see Figure 7.66).

Alternatively, the user can exported created polylines to a <∗.pli>-file. Upon export the user
will be asked to export the data “as is” or to perform a coordinate transformation before the
export (see Figure 7.66).

Figure 7.66: Import or export a <∗.pli>-file as is or with coordinate transformation.

Deltares 104 of 562

 Set-up of a D-Flow FM model

Import and export boundary forcing data

Similar to the polylines, you can import and export boundary forcing data from/to a <∗.bc>-
file. To import forcing data the existence of a polyline with at least one matching support
point is a prerequisite. Upon importing <∗.bc> data you can select which quantities and
forcing types from the <∗.bc>-file should be imported and with which overrwrite options (see
Figure 7.67). Similarly, you can export boundary forcing data. As an additional exporting
feature you can select whether you would like to export: 1) all forcing data into one file, 2) as
separate files per boundary, 3) as separate files per process or 4) as separate files per quantity
(see Figure 7.68).

T
AF
DR

Figure 7.67: Import or export a <∗.pli>-file as is or with coordinate transformation.

Deltares 105 of 562

 Set-up of a D-Flow FM model

T
AF
DR

Figure 7.68: Import or export a *.pli file as is or with coordinate transformation.

7.4.8.4 Overview of boundary conditions in attribute table (non-editable)

The attribute table of the boundary conditions gives an overview of all specified boundary
polylines and corresponding forcing (see Figure 7.69). This attribute table can be opened by
double clicking ‘Boundary Conditions’ from the project or Map window. Most of the features
in the attribute table are non-editable, except for the optional (multiplication) factor and offset
per quantity per polyline. With these settings you can integrally multiply all data on a polyline
with a factor and/or add an offset to it.

Deltares 106 of 562

 Set-up of a D-Flow FM model

T
AF Figure 7.69: Overview of all boundary conditions in attribute table

7.4.9 Physical parameters

The physical parameters attribute is used to set all physical parameters of your model. When
it is expanded in the Project window, it shows four attributes; roughness, viscosity, diffusivity
and wind.
DR

Figure 7.70: The physical parameters in the Project window

7.4.9.1 Constants
In the Physical Parameters tab, the user can adjust the value of Gravity [m/s2 ] under Others
and Default water density [kg/m3 ] under Density.

7.4.9.2 Roughness
Bed roughness can be specified as a uniform value or as a coverage (e.g. a spatially varying
field). The uniform values as well as the roughness formulation (i.e. Chézy, Manning, White-
ColeBrook or Z0 ) can be edited in the ‘Physical Parameters’ tab, which opens upon double
clicking ‘Roughness’ in the Project window (Figure 7.71). Note: The latter is not yet work-
ing. In this tab you can also specify the linear friction coefficient, linear friction Umod, wall
behaviour (free slip or partial slip) and wall ks for partial slip.

In case of spatially varying bed roughness you can double click the quantity in the Project
window or select it from the dropdown box in the Spatial Operations ribbon (Figure 7.72).
Then the spatial editor is activated, which you can use to edit spatially varying fields. For
more information on how to use the spatial editor you are referred to Appendix H.

Deltares 107 of 562

 Set-up of a D-Flow FM model

T
Figure 7.71: The section of the ‘Physical Parameters’ tab where you can specify rough-
AF ness related parameters and formulations.
DR

Figure 7.72: Roughness activated in the spatial editor to create/edit a spatially varying
field

Deltares 108 of 562

 Set-up of a D-Flow FM model

7.4.9.3 Viscosity
The eddy viscosity can be specified as a uniform value or as a coverage (e.g. a spatially
varying field). In the ‘Physical parameters’ tab you can specify the uniform values for the
horizontal and vertical (in case of 3D simulations) eddy viscosity and diffusivity (Figure 7.73).

In case of spatially varying viscosity you can double click the quantity in the Project window or
select it from the dropdown box in the Spatial Operations ribbon (Figure 7.74). Then the spatial
editor is activated, which you can use to edit spatially varying fields. For more information on
how to use the spatial editor you are referred to Appendix H.

T
AF
Figure 7.73: The section of the‘Physical Parameters’ tab where you can specify (uniform)
values for the horizontal and vertical eddy viscosity and diffusivity.
DR

Figure 7.74: Viscosity activated in the spatial editor to create/edit a spatially varying field

Deltares 109 of 562

 Set-up of a D-Flow FM model

7.4.9.4 Wind
All relevant parameters, described in chapter 15 can be adjusted in the following sub-tab.

T
AF
Figure 7.75: Overview of parameters in sub-tab Wind

7.4.9.5 Heat Flux model

The Heat flux model, described in chapter 5, needs only specification of which model to use.
DR

See the drop-down selection in Figure 7.36.

7.4.9.6 Tidal forces

The tide generating forces, described in section 3.7, can be enabled in the Processes tab,
see Figure 7.36.

7.4.10 Sources and sinks

Sources and sinks (or: intake/outfall facilities) can be used to add/extract a discharge to/from
the model or to redistribute water and constituents (such as temperature and salinity) within
the model. Sources and sinks consists of a location (defined by a <∗.pli>-file) and time series
describing the discharges (defined by a <∗.bc>-file). All the hydrodynamical considerations
behind sources and sinks are discussed in section 7.4.11.

Sources and sinks locations

Sources and sinks can be added to the model using the corresponding icon from the Map
ribbon (Figure 7.76). When the sources/sinks icon is active you can add them as polyline
elements in the central map using the left mouse button. Each polyline element is closed by
double clicking the left mouse button.

Note: Please note that the length of the polyline elements is not taken into account in the
handling of sources and sinks (e.g. it is modeled as an instant redistribution of water and
constituents without delays and friction losses).

Polyline elements starting outside the model domain and going inward are sources and,
vice versa, polyline elements starting inside the model domain and going outward are sinks.
Polyline elements starting and ending within the model are intake/outfall type of discharges.

Deltares 110 of 562

 Set-up of a D-Flow FM model

The drawing direction determines the direction of the discharge indicated by an arrow (Fig-
ure 7.77). In case of a source the direction of the last polyline element determines the direction
of flow momentum into the model.

Note: The ‘reverse’ line option — to switch the discharge direction without having to redraw
the source/sink — is not implemented.

T
Figure 7.76: Activate the sources and sinks editing icon in the Map ribbon
AF
DR

Figure 7.77: Add sources and sinks in the central map using the ‘Sources and sinks’ icon.

Sources and sinks time series

After drawing the sources/sinks locations in the central map, they appear under ‘Sources and
sinks’ in the Project window (Figure 7.78). Either by double clicking the sources/sinks in the
Project window or the line element in the central map, you can open the sources and sinks
editor (Figure 7.79). In this editor you can specify the discharge time series as well as the
corresponding constituents (for example salinity and temperature, depending on the active
physical processes). The time series of water discharges are always defined as absolute
values. For the time series of constituents the following applies:

⋄ For sources the constituent time series are absolute values

⋄ For sinks the constituent time series are determined by the modeled values
⋄ For sources and sinks (intake/outfall relationships) the constituent time series are the ex-
cess values (e.g. on top of the modeled values)

Deltares 111 of 562

 Set-up of a D-Flow FM model

Figure 7.78: Sources and sinks appearing in the Project window

T
AF
Figure 7.79: Specifying time series for sources and sinks in the sources and sinks editor

7.4.11 Intakes, outfalls and coupled intake-outfalls

DR

Many engineering studies concern the design of intakes and outfalls. For instance, studies
about positioning of waste water diffusers or coupled intake-outfall design for cooling water
at power plants. Intakes and outfalls can be modeled using sinks and sources. A source
is a point in the model where a discharge Q in [m3 /s] is prescribed by a time series ASCII
file (section C.4) with at least two columns and, depending on the model settings, possibly
more. For each optional constituent that is modelled, an extra column is required. Best known
constituents are salinity and temperature and the values in the time series file should be
specified as salinity increase in [ppt] and temperature increase in [◦ C].
1 When salinity and temperature are not used in the computation:
Model expects two columns, where the first column is the time in minutes, the second is
the discharge in [m3 /s].
2 When either salinity or temperature is used in the computation:
Model expects three columns, where the first column is the time in minutes, the second is
the discharge in [m3 /s], the third column contains either the salinity (increase) in [ppt] or the
temperature (increase) in [◦ C]. Note that third column can be either salinity or temperature
depending which constituent is used in the model and which is not.
3 In general, when other constituents are also modelled (e.g. one or more sediment frac-
tions, passive tracers), the column order is as follows: Time, Discharge, Salinity?, Tem-
perature?, (Sed.frac 1, . . ., Sed.frac n)?, Spiral flow intensity?, (Tracer 1, . . ., Tracer n)?.

The location of the source or sink is specified in a polyline file (section C.2), containing a
polyline with either multiple points or just one point. If two or more points are specified, a
coupled source sink pair is made, the first point is the FROM (or sink) point, the last point is
the TO (or source) point. Three variants may occur:
1 Sink point side lies inside a grid cell A, source point also lies inside a grid cell B (A may
equal B, but that is rarely useful): water is extracted from cell A and transported to B.

Deltares 112 of 562

 Set-up of a D-Flow FM model

2 Sink point lies outside of the grid, source point lies in a grid cell B: water is discharged into
B, a bit like an inflow discharge boundary condition.
3 Sink side lies inside a grid cell A, source side lies outside of the grid: water is extracted
from A, a bit like an outflow discharge boundary condition.

Specifying a negative discharge value effectively interchanges the role of the source and sink
points. If only one point is in the <∗.pli> file, it is assumed to be a source point. Specifying a
negative discharge turns the source into a sink.

For 3D computations, the polyline file should have a third column with z -values. It is good

T
practice to change the <∗.pli> file into a <∗.pliz> file. The z -values are used to determine
in which vertical grid cell the source and/or sink lie. The layer number can vary in time in
sigma models.
AF
In the case of a coupled pair of sink source points (variant 1), the third and fourth column with
the salinity and temperature specification are interpreted as delta salinity and delta tempera-
ture. So the values at the source point become the values at the sink point plus the specified
delta values.

The sources and sinks are specified in the new <∗.ext> as follows:

[SourceSink]
id = SourceSink_1
locationFile = chan1_westeast.pli
discharge = chan1_westeast.bc
salinityDelta = chan1_westeast.bc
DR

...
area = 1.5

Warning:
⋄ Deprecated: Source-sinks could also be specified in the old <*.ext> file. This will be-
come obsolete in an upcoming release and the example below is only kept for migration
purposes.

In the old <*.ext> file, the above example would look like:

QUANTITY=discharge_salinity_temperature_sorsin
FILENAME=chan1_westeast.pli # A file 'chan1_westeast.tim', with same basename
# as the polyline should be present
FILETYPE=9
METHOD =1
OPERAND =O
AREA =1.5

The specified area in the last line of this file determines (together with the specified discharge)
the amount of momentum uQ that is released at the source point. This is currently only im-
plemented in advection scheme 33 (cf. Deltares (2025a) on Momentum advection). Omitting
this line or specifying a zero area switches off the release of momentum at the source point.
The direction of the discharged momentum is in direction of the last two points of the polyline.
So a one point polyline is momentumless. Both in 2D and 3D, the momentum can only be
directed in horizontal direction.

Sources and sinks are treated explicity in the numerical scheme. This implies that the ac-
tual discharged or extracted amounts of water are limited by the velocity Courant condition

Deltares 113 of 562

 Set-up of a D-Flow FM model

Q∆t/V < 1. Not doing so could lead to severe timestep restrictions. Consider for instance
a specified extraction in case the extraction point has fallen dry. In that case, a real pump
would not be able to extract water and the specified extraction is more likely an input error
than an actual description of a physically feasible situation. So, we limit the specified dis-
charges to the local velocity Courant restriction. By specifying observation cross-sections
(section 7.4.2.3), one can compare prescribed discharges to the discharges that were ac-
tually realised in the model. In case of large differences, the discharge should probably be
distributed over a larger number of gridcells, or the extraction channel that feeds the extraction
point should be dredged.

T
When modelling freshwater inflow from a river into a sea, the vertical distribution of the dis-
charge that one should specify depends on the amount of detail available for modelling the
saline water - fresh water interface. If the river is modeled with sufficient detail, and the river
is well mixed at the upstream model boundary, the mixing process can be part of the mod-
elling and the river can be discharged over the whole vertical. If the mixing process cannot be
AF resolved in the model, for instance if the river is modeled as a point discharge adjacent to a
closed boundary, make sure that the whole river is discharged into the top layer or in the top
layers, depending on the estimated thickness of the fresh water plume at the discharge cell.
If one would have distributed the river discharge over the whole vertical, the size of the fresh
water plume would be underestimated because of too much mixing at the river discharge cell.

7.4.12 Lateral discharges

Lateral discharges prescribe additional inflow (or outflow) into the system on specific locations
in the model. Lateral discharges are merely adding (or extracting) volume to the model and
no momentum. As such, they differ from discharge boundaries (section 11.1.1.1) and source-
DR

sinks (section 7.4.11), which can add momentum as well. The input of lateral discharges
is via the external forcings file (section C.6.2.2); the following subsections describe the grid
placement and the forcing information.

7.4.12.1 Grid snapping and distribution of discharge

The spatial location of lateral discharges can be a single point or a set of grid points, and both
1D and 2D points are supported (also combined). The grid snapping depends on the type of
input:
⋄ Polygon area input via a sequence of x, y -points. The given area selects all pressure
points that lie inside this polygon. If the input contains multiple polygons, it is sufficient for
pressure points to lie in at least one of these polygons. Note that no "nesting" of polygon
rings is detected, polygons can not be used to exclude regions from the lateral discharge.

The latter two types also allow the user to limit the grid point snapping to either 1D or 2D, via
the keyword locationType, but this is optional.

When more than a single grid point (cell) is selected (only possible for polygon input), the
prescribed lateral discharge Qlat,ℓ is distributed across all selected grid cells based on the
grid cell areas. Specifically, each grid cell k in the set Llat,ℓ of selected grid cells receives
Qlat,ℓ,k , defined by:
Qlat,ℓ
Qlat,ℓ,k = Ak , (7.1)
Alat,tot,ℓ

Deltares 114 of 562

 Set-up of a D-Flow FM model

where the total area affected by this lateral is defined as:

X
Alat,tot,ℓ = Ak . (7.2)
k∈Llat,ℓ

This area-weighting ensures that the rate of change for the water levels in all selected grid
cells is the same, as far as the forcing by this lateral discharge is concerned. Thus, a lateral
discharge with a polygon shape could even be used to model local rainfall.

7.4.12.2 Forcing information for lateral discharges

T
The forcing information for lateral discharges is the intended flow rate for each of them. It can
be defined in two ways, all starting with the keyword discharge:
⋄ A constant value, e.g., discharge = 10.0, giving a constant flow rate of 10 m3 /s.
⋄ A prescribed time series, stored in a <.bc> or (deprecated) <.tim> file, e.g.,
AF discharge = forcing.bc. This is described for boundaries in section 11.1.1.1.
For laterals, the data format is the same, with one exception: one field Quantity should
have the value lateral_discharge.
⋄ An externally-provided discharge, i.e., discharge = realtime.

7.4.12.3 Output for lateral discharges

The lateral discharges can also be included in the output files for a model run. The total mass
balance contributions can be included in the history file (section F.3.1.6). This is the total sum
of lateral in- and outflows (possibly limited, see right-hand side in Equation (7.4.12.1)).
DR

7.4.13 Numerical parameters

In the numerical parameters tab, all numerical parameters related to your computation can be
set. The parameters that can be set are described in Table 7.1.

7.4.14 Output parameters

Model runs can produce various types of output files. The Map window shows the two most-
used types: (map and his(tory) output (Figure 7.80).

Figure 7.80: Output Parameters tab

The history file contains output on specific locations: time series data on observation points

Deltares 115 of 562

 Set-up of a D-Flow FM model

Table 7.1: Overview and description of numerical parameters

Parameter Description
Max Courant number The size of the time step, ∆t, is computed by the
computational kernel automatically, each time step
by means of the maximum tolerable Courant num-
ber. By default, this value is 0.7.
Wave velocity fraction The wave velocity fraction is related to stability of
the computation. By using this fraction, the velocity

T
of the flow is enlarged with the wave velocity times
this fraction. The value of this fraction is 0.1 by de-
fault.
Advection type This key depicts the ID of the advection scheme. By
default this value is 33.
AF
Water depth limiter type The limiter type for waterdepth in continuity equa-
tion: 0 means no limiter (default), 1 is the minmod
method, 2 the Van Leer method and 4 the mono-
tone central method.
Advection velocity limiter type The limiter type for the cell center advection veloc-
ity: 0 means no limiter, 1 the minmod method, 2
the Van Leer method and 4 the monotone central
method (default).
Salinity transport limiter type The limiter type for salinity transport: 0 means
no limiter, 1 the minmod method, 2 the Van Leer
DR

method and 4 the monotone central method (de-

fault).
Solver type Specification of the Poisson equation type solver
for the pressure: 1 = sobekGS_OMP, 2 =
sobekGS_OMPthreadsafe, 3 = sobekGS, 4 =
sobekGS + Saadilud (default), 5 = parallel/global
Saad, 6 = parallel/Petsc, 7 = parallel/GS.
Max degree in Gaussian elimination The maximum degree in the Gauss elimination, part
of the pressure solver. This key has the value 6 by
default.
Fixed weir scheme Or: fixed weir scheme. 0: none, 1: compact stencil,
2: whole tile lifted, full subgrid weir + factor.
Fixed weir contraction Or: fixed weir contraction. This is the fixed weir flow
width contraction factor, being the flow width = flow
width times the fixed weir contraction.
Boundary smoothing time Fourier smoothing time on waterlevel boundaries
(s).
Linear continuity Default 0; Set to 1 for linearizing d(Hu)/dx; link to
AdvecType.
Threshold for drop losses Apply droplosses only if local bed slope is larger
than this specific value.
Theta of time integration Level of explicitness/implicitness of time integration.
Downwind cell H on Q boundaries Specifies the way of the upstream discharge bound-
ary: 0 is original hu on qbnd, 1 is downwind hs on
qbnd

Deltares 116 of 562

 Set-up of a D-Flow FM model

(section 7.4.2.2), cross-sections (section 7.4.2.3) and structures (Sections 7.4.2.8 – 7.4.2.10).
The map file contains flow quantities on the entire grid at specified time intervals, and can later
be used for 2D and 3D visualizations of entire flow fields. The map file can typically turn out
much larger than the history file, and it is therefore advised to use larger time intervals for map
files than for his files.

Additionally, three more types of output can be requested: restart files, WAQ output, and
timing statistics. Restart files are a special type of map file that can later be used as initial
states in other runs. Restart files contain several additional flow quantities and are written
at specified intervals into one file per each restart time. Typically, one selects a large restart

T
interval in order not to waste disk space. WAQ output files are written by D-Flow FM and are
intended to be used as input files to subsequent D-Water Quality runs. More details on water
quality modelling can be found in chapter 18. Timing statistics can be produced both in the
diagnostics file (via Statistics output interval, for viewing basic simulation progress), and in
a separate detailed timings file (via Timing statistics output interval, for detailed performance
AF
analysis).

When double clicking the Output Parameters in the Project window, the Output Parameters
tab is highlighted below the central map. All parameters related to the output of your model
run are specified here (Figure 7.81). The most common output parameters to set are the
parameters related to the water quality files, history files, map files and restart files.
DR

Figure 7.81: Overview Output Parameters tab

For each of the three files (water quality, history, map and restart) the input parameters are
specified in the same manner (Figure 7.81). Taking his output as an example: when Write
His File is checked, the output of history file is enabled. His Output Interval determines the
interval at which the output data is stored in the file; the smaller the interval, the more detailed
the output and the larger the file. By default, history output is written from the start until the
end of the simulation. Optionally, output can be restricted to a certain time window: to specify
different output start and/or stop times, check the box next to Specify His Output Start Time
and/or Specify His Output Stop Time and enter the desired times next to the parameters His
Output Start Time and His Output Stop Time.

When Write Snapped Features is activated, then shape files with snapped data will be gen-

Deltares 117 of 562

 Set-up of a D-Flow FM model

erated for all quantities, such as fixed weirs and thin dams. For example, for fixed weirs a
crest height is specified at both end of a fixed weir polyline. In between linear interpolation is
applied, which can be checked via these shape files.

Below, the various output options are described in greater detail. There is a special require-
ment on the output parameters for His and Restart files that the Output Interval, Output Start
Time and Output Stop Time must be integer multiples of User Time Step. Optionally, the
interval ( Output Stop Time−Output Start Time) should be an integer multiple of User Time
Step.

T
Write his file
His Output Interval Time interval for history time series.
His Output Start/Stop Restrict history output to a specified time window.
time
AF
Write mass balance
totals
Write (misc.) structure
Enable detailed mass balance time series output in the his file.

Enable time series output across general structures, pumps, weirs

parameters and gates in the his file.

Write map file

Map Output Interval Time interval for map field time series.
Map Output Start/Stop Restrict map output to a specified time window.
time
Specific Map Output File containing specific time values at which to produce additional
DR

Times map output snapshots. It the value is not integer, it is firstly set to the
least integer larger than or equal to this value. If the computational
time does not hit the specified time value, the output snapshot is
chosen to be at the time closest to the specified time value.
Write water levels, etc. Several optionals for enabling/disabling certain quantities output in
the map file.

Write restart file

Restart interval Time interval for restart files.
Rst Output Start/Stop Restrict restart output to a specified time window.
time

Other output options

WAQ Output Interval Time interval for D-Water Quality files in <DFM_DELWAQ_mdu_name\*.hyd>,
etc.
Simulation statistics Interval for simulation progress output (on standard out and diagnos-
output interval tics file).
Timing statistics output Interval for detailed timings output into <mdu_name_timings.txt>
interval for expert performance analysis.

Deltares 118 of 562

 Set-up of a D-Flow FM model

Example
One example of input and output parameters (in seconds) is given in Table 7.2. Table 7.3
shows the time (after Reference Date in seconds) when output files are generated. We explain
this example as follows.
⋄ The history ile has output interval 18 seconds. No parameters are specified for His Output
Start Time and His Output Stop Time, which means that they are automatically set equal
to Start Time and Stop Time of the simulation, respectively.
⋄ The Map Output Interval is 6 seconds, and Map Output Start Time is 15 seconds. Since
the Map Output Stop Time is not given, it is set to equal to Stop Time. Moreover, we hope

T
to have output at time given in Specified Map Output as 30.5 and 42.1 seconds. These
two values are firstly set to 31 and 43 seconds, respectively, in the simulation. Then there
will be output snapshots if the computational time hit these two integers. Otherwise, as
in this example, the output snapshots will be provided when the computational time hits
the time that is greater and the closest to these integers, i.e. at 31.2 and 43.2 (as seen in
AF Table 7.3).
⋄ Three parameters are set for the output of the Rst files: the interval, start and stop time.

Input parameters Output parameters

Reference Date 2007-11-19 His Output Interval 00:00:18
User Time Step 00:00:00.3 Map Output Interval 00:00:06
Start Time 2007-11-19 00:00:03 Map Output Start Time 2007-11-19 00:00:15
Stop Time 2007-11-19 00:00:51 Specific Map Output 30.5, 42.1
DR

Rst Output Interval 00:00:09

Rst Output Start Time 2007-11-19 00:00:12
Rst Output Stop Time 2007-11-19 00:00:45

Table 7.2: Input and output parameters of the example

His file 3, 21, 39, 51

Map file 3, 15, 21, 27, 31.2, 33, 39, 43.2, 45, 51
Restart file 3, 12, 21, 30, 39, 45

Table 7.3: Time (after Reference Date in seconds) of output files

7.4.15 Miscellaneous
Within the miscellaneous sub-tab, various parameters in relation to waves and equatorial
settings can be adjusted. Table 7.4 gives an overview and description of these parameters.

Deltares 119 of 562

 Set-up of a D-Flow FM model

Table 7.4: Overview and description miscellaneous parameters

Parameter Description

Time step type Leave at default.

Turbulence model See chapter 10.
Turbulence advection Leave at default.
Water level threshold Max allowed water level difference between old and new time
step in any cell. Run will abort if exceeded. (0 means disabled)

T
Velocity threshold Max allowed velocity difference between old and new time step
in any cell. Run will abort if exceeded. (0 means disabled)
AF Dry cell threshold Flooding threshold at velocity points. Used in wetting and drying.

7.4.16 3D Layers
This tab is used to create a 3D model.

By default the model is 2D, which is specified by the parameter Kmx equal to 0.

A 3D model is created by specifying a positive number of layers (Kmx greater than 0).

The recommended type of vertical layering differs depending on the model application and
the processes that you are interested in. There are two options:
DR

⋄ Sigma-layers: Layers in the σ -model increase or decrease in thickness as the water depth
in the model increases or decreases. The relative thickness distribution of the different
layers however remains fixed.
⋄ Z-layers: Layers in the Z -model have a fixed thickness, which does not change as the
water depth in the model varies. If the water depth drops below the cumulative thickness
of all Z-layers, layer(s) will fall dry.

The most convenient way is to use sigma-layers, as follows.

Figure 7.82: Specification of sigma-layers

This way an evenly distributed vertical layering is specified (all layers are 20 percent of the
water depth).

Z-layers are specified as follows.

Deltares 120 of 562

 Set-up of a D-Flow FM model

T
Figure 7.83: Specification of Z-layers
AF Parameter
Table 7.5: Overview and description of Z-layer parameters

Description

FloorLevTopLay The floor level of the top layer

DzTop z-layer thickness of layers above level DzTopUniAboveZ
DzTopUniAboveZ The level above which the layers will have a uniform thickness of
DzTop
NumTopSig The number of sigma-layers on top of z-layers
DR

NumTopSigUniform Indicating whether the number of sigma-layers in a z-sigma-

model is constant (=1) or decreasing (=0) (depending on local
depth)
SigmaGrowthFactor Layer thickness growth factor from DzTopUniAboveZ downwards

Note: By choosing NumTopSig greater than 0, a combination of Z- and sigma-layering is

specified.

7.5 Save project, MDU file and attribute files

To save your D-Flow FM GUI project, navigate the menu ribbons to File and click Save as.
Choose a location, specify a name and click Save. Your project will now be saved in a folder
called <name.dsproj_data> and a <name.dsproj> file is written. Within this folder you will
find all input ASCII input files of your model, output files of your model (if the model was run
using the GUI) and zip folders containing your restart files. Be aware that the output files are
stored within a separate folder in which the input files of your model are stored. The output
folder on the same level as the folder containing model input files is empty.

To open a project, navigate the menu ribbons to File and click Open. Select the <∗.dsproj>-
file of choice and click Open.

Importing model or data within a D-Flow FM GUI project can be achieved in two ways. Navi-
gate the menu ribbons to File and click Import. A drop-down menu appears, allowing you to
select what you want to import (Figure 7.84).

Deltares 121 of 562

 Set-up of a D-Flow FM model

T
Figure 7.84: Model/data import drop-down menu
AF
Alternatively, you can also right mouse click on the name of your project in the Project window
and select Import. An import wizard appears, allowing you to select what you want to import
(Figure 7.85).
DR

Figure 7.85: Model/data import wizard

Exporting your model can be achieved in the same fashion as importing your model. All model
input files will be written to the folder you select. Be aware that model files exported to a folder
in which other model files with the same names are present will be overwritten.

Deltares 122 of 562

 8 Running a model

8.1 Introduction
After defining the input for the D-Flow FM hydrodynamic simulation, the computation can
be executed either via the D-Flow FM Graphical User Interface, GUI, (on Windows), see
section 8.2, or using batch scripts (on Linux and Windows). Via the GUI, the status of the
computation and possible messages are displayed in a separate messages window. When
using a batch script, all messages are written to the diagnostics file (section F.1) and inside
the terminal (stdout and stderr).

T
Use a batch script (see section 8.3) in the following cases:
1 Using MPI to run in parallel, see section 8.4
2 Using some queueing mechanism on a cluster
AF 3
4
Running some unattended simulations, while continuing to work in the User Interface
Running on Linux.

8.2 Running a scenario using the User Interface

In the Project window, select the model you want to run by clicking the first sub-item of the
desired model (Figure 9.1).
DR

Figure 8.1: Selecting the model you want to run in the Project window

Starting the calculation can be achieved in two ways. You can navigate the menu ribbons; go
to “Home” and in the group Run click on the button “Run Current”. To run all models that are
opened in the Project window, click on “Run All” (Figure 8.2).

Figure 8.2: Group Run in Home ribbon

Alternatively, you can right mouse click the first attribute in the Project window of the model
you want to run. Next, click “Run Model” to start the calculation. If you first select the model
you want to run, the properties window (“View” “Properties”) will show several properties of
the model you selected. If you set “ShowModelRunConsole” to true, the model run console
of the computational core will be shown during the calculation, providing you with additional
information during the model run (Figure 8.3).

Deltares 123 of 562

 Running a model

T
AF Figure 8.3: Run console D-Flow FM User Interface

If you cancel the run by clicking “Cancel all activities”, model results are stored up to the point
where you cancel the run.

8.3 Running a scenario using a batch script

DR

In general, the following steps have to be carried out:

1 Set-up a D-Flow FM model in the GUI on Windows.
Currently, this is only possible for 2DH (depth-averaged) model simulations. Validate the
model.
2 Export the model to either a ’DIMR configuration’ or a ’Flow Flexible Mesh model’, as
described in section 6.2 of this user manual. A ’DIMR configuration’ is necessary when
the computation consists of a D-Flow FM model integrated with another kernel (e.g. D-
RTC or D-Waves). A ’Flow Flexible Mesh model’ is optional for a standalone D-Flow FM
computation.
In case of a 3D model, change the input for the 3D keywords (number of layers, layer
percentages, . . . ) via the GUI or manually. Note: The GUI for 3D modelling contains
limited functionality for 3D yet.
3 Copy the complete set of model input files to the machine doing the computation (Windows
or Linux).
4 In case of a parallel MPI computation: partition the model. Partitioning can be executed
both on Windows (before copying the input files) and Linux (after copying the input files),
see section 8.4.2.
5 Start the D-Flow FM model simulation. See section 8.3.2.
6 In case of a parallel MPI computation: after completion of the model simulation, map
merging of the output files is often carried out in order to simplify the postprocessing. See
section 8.4.4.2.
7 Use QUICKPLOT for postprocessing, see section 8.4.4 and the QUICKPLOT user manual.

Deltares 124 of 562

 Running a model

8.3.1 Commandline executables

Executables should be called via run-scripts prepared by Deltares. To use these prepared
scripts, you are supposed to write a one-lined script in your working directory.

Windows (example of a one-lined script that calls a Deltares-prepared script):

call <installDir>\x64\bin\run_dimr.bat

Linux (example of a one-lined script that calls a Deltares-prepared script):

<installDir>/lnx64/bin/run_dimr.sh

T
Note: Example models, with one-line-scripts, are included in the (open source) code. After
registering yourself at https://oss.deltares.nl/, you can have a look at:
https://svn.oss.deltares.nl/repos/delft3d/trunk/examples
/12_dflowfm/test_data/e100_f02_c02-FriesianInlet_schematic_FM
AF Advantages of this construction:
⋄ The script will take care of preparations like setting environment parameters
⋄ The script will call the correct binary with the correct arguments
⋄ Uniform look and feel
⋄ In case of multiple installations, there is no confusion about what version is being used.
The prepared scripts, located in an installation directory, will always use the executables
in that same installation directory.

Differences between the Windows and Linux prepared run-scripts:

On Windows:
DR

⋄ The location of the prepared scripts is x64\<modulename>\scripts inside

<Your installation base dir>\plugins\DeltaShell.Dimr\kernels\
where <Your installation base dir> is typically:
c:\Program Files\Deltares\Delft3D Flexible Mesh Suite HMWQ (xxxx.xx)
⋄ The file extension is <.bat> or <.cmd>.

On Linux:
⋄ The location of the prepared scripts is lnx64\bin inside
<Your installation base dir>
where <Your installation base dir> is typically:
/opt/delft3dfm/xxxx.xx
⋄ The file extension is <.sh> or no extension at all.

8.3.2 Running D-Flow FM

Export the input files in the GUI, see section 6.2. Be sure that the GUI produces the ’DIMR
configuration’ file too, typically called <dimr_config.xml>. Write a one-line-script to call the
’run_dimr’ script in the installation directory. The easiest Windows example <run.bat>:

call <installDir>\x64\bin\run_dimr.bat dimr_config.xml

The easiest Linux example <run.sh>:

Deltares 125 of 562

 Running a model

<installDir>/lnx64/bin/run_dimr.sh dimr_config.xml

Put the one-line-script in the same directory as file <dimr_config.xml> and execute it; on
Windows double-click the script or execute it in a command box; on Linux execute it in a
command box.

Note: Example models, with run scripts, are included in the (open source) code. After
registering yourself at https://oss.deltares.nl/, you can have a look at:

T
https://svn.oss.deltares.nl/repos/delft3d/trunk/examples
/12_dflowfm/test_data/e100_f02_c02-FriesianInlet_schematic_FM

Remarks:
⋄ Executing <dflowfm> instead of <dimr> is an option when running D-Flow FM stand-
AF alone (not coupled to D-Water Quality, D-RTC, D-Waves etc.). To do this, replace
’run_dimr’ by ’run_dflowfm’ and the dimr config file by the mdu-file in the one-line-script.
⋄ Calling ’run_dimr’ with the argument --help will show the options
⋄ Argument after the separator ’--’ are passed through to the D-Flow FM kernel (if the
D-Flow FM kernel is the only kernel being started).

8.4 Parallel computing using MPI

8.4.1 Introduction
DR

This section describes parallel computing with D-Flow FM based on the Message Passing
Interface system (MPI). This can be run both on computing clusters with distributed memory
as well as shared memory machines with multiple processors and/or multiple CPU cores. A
parallelMPI computation can use multiple machines in a Linux cluster. On Windows, only one
machine can be used.

The goal of parallelization of D-Flow FM is twofold: faster computations and the ability to
model problems that do not fit on a single machine. A less powerful, yet possibly attrac-
tive performance improvement is offered by D-Flow FM’s OpenMP-based parallelization (sec-
tion 8.5.1).

Technical backgrounds on the parallel algorithms in D-Flow FM are described in the Technical
Reference Manual Deltares (2025a).

Workflow of a parallel run

A parallel MPI run divides the work between multiple processes. The model is split in submod-
els or partitions. A separate process is started for each partition, solving the equations on that
partition. It will communicate with the neighbouring processes where needed and generate
output only for it’s own partition. Given a whole model, the workflow is as follows:
1 Partition the model (mesh and model definition file)
2 Execute the parallelMPI job on a multi-core machine or on several machines in a (Linux)
cluster
3 Visualize the results from partitioned output files.

Deltares 126 of 562

 Running a model

8.4.2 Partitioning a model

In D-Flow FM a model is defined by the model definition file, <.mdu>, the network (mesh)
file, <_net.nc>, external forcing/boundary condition files, <.ext>, et cetera. Partitioning a
model concerns partitioning of <.mdu>-file and the network file <_net.nc>. Other files are
shared by all submodels and do not need to be partitioned, they should only be available to
all processes.

Partitioning a model can be done by executing run_dflowfm, which is slightly different on

Windows and Linux. It is recommended to use a runscript to partition the model that takes

T
care of paths and environment parameters:
⋄ Windows
On Windows one has to use the batch file run_dflowfm.bat, please see the following
example:
AF "<installDir>\x64\bin\run_dflowfm.bat" "--partition:ndomains=8:
icgsolver=6" example.mdu

Note that the double quotes, "...", are used for the input arguments, in order to preserve
equal-sign, =, when passing those input arguments to the batch file.
⋄ Linux
On Linux one has to use run_dflowfm.sh:
<installDir>/lnx64/bin/run_dflowfm.sh --partition:ndomains=8:icgsolver=6
example.mdu
DR

The run_dflowfm command reads the name of the network file from mdu-file, and gener-
ates n subdomain network files by the METIS software package (See Deltares (2025a) and
references mentioned therein). Then, it creates n subdomain mdu-files where the parallel
Krylov solver icgsolver is set to i, which can be 6, the PETSc solver (recommended), or,
7, the parallel CG with MILU block preconditioning.

The partition example above results into 8 subdomain mdu-files, and 8 subdomain network
files. The subdomain mdu-files have names as <example_000j.mdu>, j=0,1,...,7. The differ-
ent items in, e.g. <example_0000.mdu> with respect to the original mdu-file are:

[geometry]
NetFile = example_0000_net.nc

[numerics]
Icgsolver = 6 (or 7)

Assuming that the specified network file in the original mdu-file is <example_net.nc>, then
the 8 subdomain network files have names <example_000j_net.nc>, j=0,1,...,7. In other
words, they are:

example_0000_net.nc example_0003_net.nc example_0006_net.nc

example_0001_net.nc example_0004_net.nc example_0007_net.nc
example_0002_net.nc example_0005_net.nc

Moreover, by default a separate file <DFM_interpreted_idomain_example_net.nc> is gener-

ated, which includes partition domain information and cell information. One can switch off

Deltares 127 of 562

 Running a model

generating this file by adding in the original mdu-file in the chapter output the keyword
Writepart_domain = 0.

Note: In all the partitioning commands shown in this subsection, one can specify a network
file <example_net.nc>, instead of the mdu-file <example.mdu>. This will only partition the
network file. However, we strongly suggest to use the mdu-file in the partitioning commands,
which partitions both the mdu-file and the network file. The reason is, when a dry points or/and
enclosure file is specified in the mdu-file, the partition tool will first delete dry areas based on
these files, and then do the partition. If one specifies network file in the partitioning command,
then the resulting subdomain network files still include dry areas. Then after running the

T
parallel simulation, the output map files do not contain those dry areas. These will bring
inconsistence and further yield a problem if merging the map files.

8.4.2.1 More options for the partitioning

AF The commands in section 8.4.2 partitions the model, including partitioning the network file.
This section describes the full possibilities for partitioning a network (mesh). The mesh can
be automatically partitioned with the METIS software package, or manually by supplying poly-
gons that define the subdomains. They both produce a cell colouring of the original mesh.
In each subdomain, the cells are assigned the same colour, and augmented with ghost cells.
This information is saved in variable "idomain" in the resulting partitioning mesh files, e.g.
<example_NNNN_net.nc>, where NNNN is a subdomain index.

Partitioning with METIS

The command (on Linux):
DR

<installDir>/lnx64/bin/run_dflowfm.sh --partition:ndomains=n:icgsolver=i <mdu-file>

is a basic command to partition with METIS. An advanced command, which enables more
options, is:

<installDir>/lnx64/bin/run_dflowfm.sh --partition:ndomains=n[:method=0|1][:genpolygon=0|1]
[:contiguous=0|1][:ugrid=0|1][:seed=i] <mdu-file>

The explanation of these options is as follows:

The partition method can be chosen via setting method=1, the multilevel K-Way method
(default), or method=0, the Recursive Bisection method. We refer to Karypis (2013) for
more details about these two methods.

Option genpolygon specifies if the command generates a partition polygon file (genpolygon=1),
or not (genpolygon=0, default).

By default FM enforces contiguous partitioning, i.e. contiguous=1. This can be switched

off by setting contiguous=0. Only the multilevel K-Way method can enable the contiguous
partition. If one requires the Recursive Bisection method, then it is not possible to enforce
contiguous partitioning.

In the situation when one gets error message "The above METIS error message is not a
problem. It means that partitioning failed for k-way method with option contiguous=1 because

Deltares 128 of 562

 Running a model

the input graph is not contiguous. Retrying partitioning now with contiguous=0.", it is no need
to worry because it retries partitioning without enforcing contiguous.

Option seed=i with i a user-defined integer allows to pass a random seed to the METIS
partitioner. This allows the user to have reproducible partitioning result between separate
runs.

Note: These options can be used with scripts run_dflowfm.bat and run_dflowfm.sh.
Note: Partitioning script generate_parallel_mdu.sh is outdated and should not be
used.

T
Partitioning with manually supplying polygons
If the user wants to manually partition the mesh instead of applying METIS, then he has to
provide a polygon file <userpol.pol> which determines the mesh partition. In this situation,
AF
he can use the following command:

<installDir>/lnx64/bin/run_dflowfm.sh --partition:icgsolver=i <mdu-file> <userpol.pol>

Notice that this command should not use the option ndomains, but adds the polygon file
name at the end. If accidentally, ndomains is specified, the provided polygon will be ignored
and partitioning falls back to using METIS.
DR

Note: Similarly, to use a script run_dflowfm.bat or run_dflowfm.sh, one can re-

move option ndomains, and add the polygon file name at the end of the command, as
below:
⋄ On Windows one can use batch file run_dflowfm.bat, please see the following ex-
ample:
"<installDir>\x64\bin\run_dfmoutput.bat" "--partition:icgsolver=6"
example.mdu part.pol

Note that " " is used for the input arguments, in order to preserve = when passing those
input arguments to the batch file.
⋄ On Linux one can use run_dflowfm.sh:
<installDir>/lnx64/bin/run_dflowfm.sh --partition:icgsolver=6
example.mdu part.pol

Where, ’part.pol’ is the name of a partition polygon file.

And the partitioning obeys the following rules:

⋄ if the polygons have a z -value specified, it is considered a subdomain number,
⋄ if the polygons have no z -value specified, its order determines the corresponding subdo-
main number,
⋄ if a cell is not inside at least one polygon, it is assigned to subdomain 0,
⋄ In order to avoid that subdomain 0 will be empty, which isn’t allowed, the partitioning with
polygons should not cover the whole model domain. Then, automatically some cells will
be in subdomain 0.
⋄ Thus, if n − 1 partitioning polygons are used and some cells aren’t in these polygons,
then a partitioning in n subdomains is generated by the partition method.

Deltares 129 of 562

 Running a model

⋄ if a cell is inside only one polygon, it is assigned to the subdomain defined by that polygon,
⋄ if a cell is inside more than one polygon, it is assigned to the subdomain with the highest
number.

In other words, the polygons may be overlapping and the largest subdomain number is taken
in the overlapping regions. If the polygons have no z -value, the polygon order determines the
corresponding subdomain number, i.e. the first polygon corresponds to subdomain 1 et cetera
and there is no polygon defining subdomain 0.

T
Partitioning the mesh with METIS via the User Interface
A separate mesh partitioning is not needed when following the instructions for partitioning a
complete model in section 8.4.2. This section describes the full posibilities for partitioning a
mesh.
AF
We will firstly focus on the METIS partitioner. Partitioning the mesh from within the User
Interface is achieved by the following steps. In the Project window, select the model you want
to run by means of clicking on the desired model (Figure 9.1). A right-mouse click will open the
context menu, then select Export.... In the window Select Type of Data..., choose Partition
exporter and the partitioning dialog will appear (Figure 8.4).
DR

Figure 8.4: Partioning exporter dialog

Enter the desired amount of subdomains, and typically leave the contiguous option switched
off and the solver type at its default. After pressing OK, a file dialog will appear. Enter the
name of the mdu-file, without any trailing ’_000x’ partition numbers: these will be added
automatically.

Partitioning the mesh with the graphical user interface is achieved by the following steps:
You are prompted for Contiguous domains are not necessary for parallel computations in D-
Flow FM and often METIS produces contiguous subdomains without enforcing it. Still, some
users may want to explicitly enforce contiguous domains. If you want to do so, make sure
that your unpartitioned mesh is contiguous. Not being so may cause errors, Note that there
is no polygon defining subdomain 0. Parts of the mesh not confined by any polygon are
assumed to be in subdomain 0. In other words, there are at least N − 1 polygons defining
N subdomains. In that case, regenerate the cell colors/domain numbers again by selecting
Operations → Generate domain numbers (polygon or METIS). Note that you will not be asked
to specify the number of subdomains. The cell coloring/domain numbering is now based on
the (modified) polygons and not produced by the METIS partitioner. Manual partitioning with
user-specified polygons will be explained in the next section, The entered mesh filename is a
basename that will be used to derive the partitioning filenames, e.g. <example_net.nc> will

Deltares 130 of 562

 Running a model

produce:

8.4.2.2 Partitioning the mdu-file

A separate mdu-partitioning is not needed when following the instructions for partitioning a
complete model in section 8.4.2.

Partitioning script generate_parallel_mdu.sh is outdated and should not be used.

T
8.4.2.3 Remaining model input
A parallel run of a D-Flow FM model needs only partitioned <.mdu> and <_net.nc> files.
All other model input is the same as for a standalone run, e.g., meteo forcings, boundary con-
ditions, observation stations and more. These are generally copied to the working directory
by the parallel job submission script.
AF
8.4.3 Running a parallel job
On Windows, parallel jobs can only be executed using one node/machine/PC. On Linux, mul-
tiple nodes/machines can be used.

Note: Example models, with run scripts, are included in the (open source) code. After
registering yourself at https://oss.deltares.nl/, you can have a look at:
https://svn.oss.deltares.nl/repos/delft3d/trunk/examples
/12_dflowfm/test_data/e02_f14_c040_westerscheldt
DR

8.4.3.1 A parallel simulation via DIMR

Below is shown how to start a parallel simulation on Linux:

<installDir>/lnx64/bin/run_dimr.sh -c 3 dimr_config.xml

And for Windows:

call <installDir>\x64\bin\run_dimr_parallel.bat 3 dimr_config.xml

This assumes that the model has already been partitioned in three partitions. When running
via DIMR, in the file <dimr_config.xml>, in the section about the D-Flow FM component, the
following two lines must be present:

<process>0 1 2</process>
<mpiCommunicator>DFM_COMM_DFMWORLD</mpiCommunicator>

where <process> must match exactly with the number of processes.

A Linux cluster usually has a queueing system with a scheduler. Example submission scripts
are available upon request.

Deltares 131 of 562

 Running a model

8.4.3.2 A parallel simulation on Linux via D-Flow FM

To run a parallel simulation with a D-Flow FM model on a Linux cluster you have to prepare a
submission script with the specific options that the job scheduler on your cluster requires.

Below a simple example is shown of the D-Flow FM submission script for a Linux cluster with
the Grid Engine scheduler:

#!/bin/bash

T
#$ -V
#$ -q test
#$ -cwd
#$ -N My_DFlowFM_JOB
#$ -m bea
#$ -M [email protected]
AF export LD_LIBRARY_PATH=$DFLOWFM/lib:$LD_LIBRARY_PATH
export PATH=$DFLOWFM/bin:$PATH

mpiexec -np 4 dflowfm --autostartstop YOUR_MDU_FILE.mdu >out.txt 2>err.txt

Assumptions related to the simplified example above:

⋄ The D-Flow FM simulation has already been partitioned into four domains.
⋄ The location of the D-Flow FM binaries has been stored in environment parameter ’DFLOWFM’.
⋄ D-Flow FM is used as a standalone executable, not as part of a DIMR computation.
DR

⋄ The example script is used in the actual submission command on a Linux cluster, together
with a specificiation of the number of nodes to be used.

The options used above are:

-V Specify that all environment variables active within the qsub utility be exported
to the context of the job.
-q Specify the queue ’test’ to be used for this job, if absent default queue is used.
-cwd Execute the job from the current working directory.
-N Specify the name of the job.
-m Specifies which message type should be emailed (b=beginning of job, e=end of
job, a=abort of job.
-M Specifies the email address to send the notification.

In order to submit more complicated, e.g. multi-node simulations, additional options that are
scheduler dependent have to be added.

8.4.4 Visualizing the results of a parallel run

The map and history output files (as introduced in section 7.4.14) deserve special attention in
parallel runs.

The history file — with time series for observation points, structures and more — is written
only by process #0, and all model-global data has already been aggregated into that single
file: <mdu_name_0000_his.nc>.

The map file — with full-grid output of flow fields — is written for each domain separately as
<mdu_name_000X_map.nc>. This saves communication overhead during the parallel run.

Deltares 132 of 562

 Running a model

The partitioned map files contain duplicate points, since each file also contains the domain’s
ghost nodes. For postprocessing these map files, two options are now available:
1 Direct plotting of the set of all map files in Delft3D-QUICKPLOT: the partitioned file series
will be recognized automatically, and the partion results will be drawn on top of each other.
For water levels this gives good results.
2 Merging the partioned map files into a single global map file with the dfmoutput tool.
The resulting map file can then be loaded again in Delft3D-QUICKPLOT and other post-
processing utilities.

T
8.4.4.1 Plotting all partitioned map files with Delft3D-QUICKPLOT
When opening one of the partitioned map files into Delft3D-QUICKPLOT, it will automatically
detect that the map file is part of a series. An additional select list Domain appears, see
Figure 8.5. Select either “all partitions”, or a partition of your choice, and proceed with the
AF plotting as normal (section 9.3).
DR

Figure 8.5: Domain selector in Delft3D-QUICKPLOT for partitioned map files.

8.4.4.2 Merging multiple map files into one

The partitioned map files of a parallel model run can be merged into a single global map file
with the dfmoutput tool. It cuts off ghost nodes, and concatenates all grid points, taking
care of correct global renumbering. Usage:

dfmoutput.exe mapmerge --infile FILE1 FILE2 [--outfile DSTFILE]

where FILE1, FILE2 are the input files, e.g. <mdu_name_0000_map.nc>, <mdu_name_0001_map.nc>,
and you can add more input files here. And DSTFILE is an optional output file name (the
default is <mdu_name_merged_map.nc>).

It is recommended to use a runscript, that takes care of paths and environment parameters.
Please see the following:

Deltares 133 of 562

 Running a model

⋄ Windows
On Windows one can use batch file <run_dfmoutput.bat>:
"<installDir>\x64\bin\run_dfmoutput.bat" mapmerge
--infile FILE1 FILE2 [--outfile DSTFILE]

Remarks:
⋄ Note that for this script the number of arguments is limited to 9. Therefore, consider-
ing 2 arguments mapmerge and --infile, only maximal 7 map-file names could
be passed, which means that only maximal 7 map-files can be merged if using the
option --infile.

T
⋄ If one wants to merge more than 7 map-files using this batch file, then the user should
use --listfile instead of --infile, then one can use the command option
--listfile (see the list of more advanced options below), instead of --infile.
An example is:
dfmoutput.exe mapmerge --listfile list.txt
AF where file list.txt contains a list of names of all input map files, as shown below,
with one file name on a single line.
model_0000_map.nc
model_0001_map.nc
model_0002_map.nc
model_0003_map.nc
model_0004_map.nc
model_0005_map.nc
model_0006_map.nc
model_0007_map.nc

⋄ Linux
DR

On Linux one can use <run_dfmoutput.sh>:

<installDir>/lnx64/bin/run_dfmoutput.sh -- mapmerge --infile FILE1 FILE2
[--outfile DSTFILE]

Note, in this command, there is a space between "--" and "mapmerge". Moreover, one
can also use option "--listfile" instead of "--infile".

Remark:
⋄ Since a restart file is a special type of map-file, partitioned restart files can also be
merged using the above command.

The built-in help gives a list of more advanced options:

> dfmoutput mapmerge --help

usage: dfmoutput mapmerge [--infile FILE1 [FILE2 FILE3...]] [--listfile LISTFILE]
[--outfile DSTFILE] [--force] [--help] [--version]

Merge multiple map files from parallel run into one.

Optional switches:
--infile FILE1 [FILE2...], -i FILE1 [FILE2...]
default value
One or more input files.
--listfile LISTFILE, -F LISTFILE
Pass contents of LISTFILE as input files.
--outfile DSTFILE, -o DSTFILE
Write output to file DSTFILE. Default: <model>_merged_map.nc
--force, -f
default value .false.
Force overwriting of existing output file.
--help, -h

Deltares 134 of 562

 Running a model

Print this help message

--version, -v
Print version

Examples:
dfmoutput mapmerge --infile model_0000_map.nc model_0001_map.nc
dfmoutput max_running_mean --infile hisfile.nc
dfmoutput max25 --infile hisfile.nc
dfmoutput genfilter --infile hisfile.nc --intval 6

Merging 2D map files

T
2D (or 3D) map file merging has a few special aspects:
⋄ All data variables and underlying spatial coordinate variables are merged into one file,
cutting off all ghost cells.
⋄ Near partition boundaries, the data written to the merged file is taken from the input parti-
AF tioned file that "owns" the grid locations near those boundaries. For grid cells, this is the
partition in whose interior the grid cells lie. For shared mesh nodes and edges the partition
is based on the lowest partition number owning the grid cell that they are part of.
⋄ The order of the merged data values is in a so-called concatenated way. This means that
all non-ghost points are concatenated domain-by-domain, keeping the local ordering for
each partitioned submodel. This means that the output map file is likely to have a different
ordering than the single map file from a sequential model run. This should not be an issue
for any postprocessing, since all CF- and UGRID- domain variables have been merged in
a consistent way, so the file remains correctly self-contained.
⋄ Any user-defined vector dimensions for multidimensional data are also copied, if they are
necessary for variables defined on the spatial domain (for example velocity components,
DR

tracers or vertical layering).

8.5 Run time

The actual run time of a model can vary considerably depending on a variety of factors such
as:

⋄ The problem being solved, characterised by the number of active grid points, the number
of layers in the vertical or the number of processes taken into account.
⋄ The length of the simulation in time and the time step being used.
⋄ The hardware configuration that is used and the work load of the processor.

For this reason, only some general considerations are given to determine the run time of a
hydrodynamic simulation. On a PC or a workstation without separate I/O-processors the CPU
time is the sum of the processor time and the I/O time.

The processor time required for a simulation is primarily determined by:

⋄ The model definition, i.e., the number of active grid points and the number and type of the
processes taken into account.
⋄ The length of the simulated period in terms of the number of time steps executed.

The I/O time is determined by:

⋄ The number of times the computed data are written to history, map, restart files and other
communication files for water quality or wave model couplings.
⋄ The number of observation points, cross-sections and the number of output parameters.

Deltares 135 of 562

 Running a model

The simulation performance is defined as the CPU time per grid point per time step per con-
stituent:
CPU time
simulation performance = [system seconds]
Dnt · Ndx
where:
Dnt is the number of time steps executed
Ndx is the number of flow nodes

T
The simulation performance is written to the diagnostic file at the end of the simulation.

8.5.1 Multi-core performance improvements by OpenMP

D-Flow FM has built-in support for multi-core parallellism using OpenMP1 . This speeds up
AF calculations by employing multiple processor cores in a single (shared-memory) computer,
e.g., a modern-day notebook. OpenMP-parallellism in D-Flow FM does not scale as well as
MPI-parallellism (section 8.4), but it comes for free (not any change to model input necessary)
and can give a welcome performance improvement (approximately double speed on an Intel
quadcore CPU). It is strongly advised to limit the number of OpenMP-threads to one less than
the number of physical cores in your machine, thus also ignoring any hyperthreading. Mixing
OpenMP with MPI is possible, but the optimum with respect to computation time is expected
with only MPI parallellisation.

An OpenMP example on Windows:

DR

set OMP_NUM_THREADS=3
call <installDir>\x64\bin\run_dimr.bat dimr_config.xml

An OpenMP example on Linux:

export OMP_NUM_THREADS=3
<installDir>/lnx64/bin/run_dimr.sh dimr_config.xml

8.6 Files and file sizes

For estimating the required disk space the following files are important:

⋄ history file
⋄ map file
⋄ restart file

8.6.1 History file

The size of the history file is determined by:

⋄ The number of monitoring points (observation points + cross-sections): H1.

⋄ The number of quantities stored: H2.
⋄ The number of additional process parameters, such as salinity, temperature, constituents
and turbulence quantities, taken into account in the simulation: H3.
1
http://www.openmp.org

Deltares 136 of 562

 Running a model

⋄ The number of time the history data is written to the history file: H4.

You can estimate the size of a history file (in bytes) from the following equation:

size history file = H1 · (H2 + H3) · H4 · 8 bytes.

As a first approximation you can use H2 = 8.

Example

T
For a 2D simulation with density driven currents (salinity and temperature), a simulated period
of 12 hrs 30 min, a time integration step of 5 minutes, 30 monitoring points and each time
step being stored, the size of the history file will be of the order of 384 kBytes. For the same
model but now with 10 layers in the vertical the file size will increase to about 4 MBytes. These
AF estimates show that history files are rather small. Unless the number of monitoring points is
excessively large the history files are typically much smaller than the map output files.

8.6.2 Map file

The size of the map file is determined by:

⋄ The size of the model, i.e. the number of grid cells multiplied by the number of layers (Ndxi
· Kmax): M1n, and the number of flow links (open grid cell edges) multiplied by the number
of layers (Lnx · Kmax): M1l.
⋄ The number of quantities stored on grid cells and flow links: M2n, M2l, respectively.
⋄ The number of process parameters taken into account, such as salinity, temperature,
DR

constituents and turbulence quantities: M3.

⋄ The number of time steps for which the map file is written: M4.

Remark:
⋄ For a more refined estimate you should distinguish between parameters that depend
or not on the number of layers used (such as the water level). For a 3D simulation the
latter quantities can be neglected, for a 2D simulation they must be accounted for. As a
first estimate we double the number of quantities M2 in a 2D simulation.

As a first approximation you can use M2n = 5, M2l = 5 for a 3D simulation and M2n = 8, M2l
= 5 for a 2D simulation.

You can estimate the size of a map file (in bytes) from the following equation:

size map file =[M1n · (M2n + M3) + M1l · M2l] · M4 · 8 bytes.

Example
For a 2D simulation with 6800 grid cells and 13000 flow links, simulation results stored for
a period of 7 days, and the file is written with an interval of 60 minutes the size of the map
file will be about 161 MBytes. For larger models the map file can easily become excessively
large, as result the map file is less frequently written, for instance every 2 or 3 hours.

Deltares 137 of 562

 Running a model

8.6.3 Restart file

A restart file is a special type of map file, where only one time snapshot per file is saved (i.e,
M4 = 1). No grid or flow geometry information is stored in a restart file, except for the flow
cell/link information (denoted by M5). Moreover, the restart files obtained after a parallel run
contain some necessary information about parallelization (denoted by M6). Similarly to the
equation of size map file above, one can write the estimating equation as follows:

size rst file = [M1n · (M2n + M3) + M1l · M2l + M5 + M6] · 8 bytes,

T
where M6 = 0 for a sequential run.

8.7 D-Flow FM command-line argument

Sometimes it’s useful to run the D-Flow FM binary from the command line, without using
any prepared script. On Linux this binary is named dflowfm. (dflowfm-cli.exe on
AF Windows). On Linux a basic non-interactive run is started by:

> dflowfm --autostartstop MDUFILE

In the box below, a full list of command-line options and arguments is shown:

> dflowfm --help

Usage: dflowfm [OPTIONS] [FILE]...
DR

FILE may be one of the following types:

*.mdu model definition file
*.cfg display settings file
*.pol, *.xyz, etc. additional model files

Options:
--autostart MDUFILE
Auto-start the model run, and wait upon completion.

--autostartstop MDUFILE
Auto-start the model run, and exit upon completion.

--noautostart MDUFILE
Disable any AutoStart option in the MDU file (if any).

--partition:OPTS (MDUFILE|NETFILE) [POLFILE]

Partitions the unstructured model+grid in MDUFILE into multiple files.
or: the unstructured grid in NETFILE into multiple files.

POLFILE is an optional polygon file which defines the partitions.

Only used when ndomains in OPTS is undefined or 0.

OPTS is a colon-separated list opt1=val1:opt2=val2:...

ndomains = N Number of partitions.
method = [123] Partition method: K-Way(1, default), Recursive Bisect
ion(2), Mesh-dual(3).
genpolygon= [01] Generate partition polygon(1), or not (0).
contiguous= [01] Enforce contiguous grid cells in each domain.
Only available when K-Way is enabled (method=1).
icgsolver = [67] Parallel CG solver (When MDUFILE is specified).
6: PETSc (default for parallel), 7: parallel GS+CG.
ugrid = [01] write cf UGRID 0.8 (0, default) or UGRID 1.0 (1)
seed = i User-defined random seed value, for reproducible
partitionings. Only used when i not equal to 0.

-t N, --threads N
Set maximum number of OpenMP threads. N must be a positive integer.

--processlibrary PROCESSLIBRARYFILE

Deltares 138 of 562

 Running a model

Specify the process library file to be used for water quality processes.

--openprocessdllso OPENPROCESSDLLSOFILE
Specify the open process dll/so file with additional subroutines to be
used for water quality processes.

--bloomspecies BLOOMSPECIESFILE
Specify the BLOOM species definition file to be used for water quality
processes.

--refine:OPTS NETFILE
Refine the unstructured grid in NETFILE from commandline.
OPTS is a colon-separated list opt1=val1:opt2=val2:...
hmin=VAL

T
dtmax=VAL
maxlevel=M
connect=[01]
directional=[01]
outsidecell=[01]
drypointsfile=<filename (*.pol, or cutcellpolygons.lst)>
AF --make1d2dlinks[:OPTS] NETFILE [-o OUTPUTFILE]
Make 1d2d links for the given NETFILE and save the resulting net.
OPTS is a colon-separated list opt1=val1:opt2=val2:...
method
linktype
= (1to1 | 1ton_emb | 1ton_lat | long) Coupling method.
= N The link type (kn3) that will be used for all links
(only for method=1to1).
connect1dend = VAL The search distance for coupling 1D endpoints.
OUTPUTFILE is the name under which the file will be saved.
When not specified, the original NETFILE will be overwritten.

--cutcells NETFILE
Cut the unstructured grid in NETFILE with the polygons specified
in a file called 'cutcellpolygons.lst'.

--no-geom-cache
DR

Do not load nor save cache file with geometry information.

-q, --quiet
Minimal output: Only (fatal) errors are shown.

--verbose[:level_stdout[:level_dia]], e.g., --verbose:INFO:DEBUG

Set verbosity level of output on standard out and in diagnostics file.
where level is in: {DEBUG|INFO|WARNING|ERROR|FATAL}
Levels are optional, default is INFO on screen, DEBUG in dia file.

-h, --help
Display this help information and exit.

-v, --version
Output version information and exit.

8.8 Restart a simulation

D-Flow FM allows to restart a simulation, not from the original starting time, but from a user-
specified time with all the information at that time. In other words, for a model which has a long
spinup time from tstart , instead of restarting from tstart , one can restart another simulation of
the same model from a later time trst , where tstart ≤ trst < tstop . And the results for times
trst ≤ t ≤ tstop are the same as in the original simulation run.

This can be achieved by following steps:

1 In order to obtain restart files <_rst.nc>, this needs to be enabled in the output parame-
ters (see section 7.4.14 for more details about how to set output parameters).
2 Run the original model from tstart to tstop , resulting in restart files.
3 To restart the simulation from time trst , in the mdu-file modify TStart to trst , and fill
in the name of corresponding restart file in RestartFile of the [restart]-section.
Moreover, place the corresponding restart file relative to the directory of this mdu-file.

Deltares 139 of 562

 Running a model

To restart a parallel simulation, one can use any of the following methods:
Method 1 On each subdomain use its own restart file.
Method 2 Merge all the subdomain restart files into a single global restart file (see section 8.4.4.2),
and then use it for all the subdomains. This means to put the name of this merged file
as RestartFile in all subdomain mdu-files. This method is supported when restarting
with the same, or a different domain partitioning. Moreover, such a merged restart file can
also be used to restart a sequential run.

The above two methods require taking care of the name of the restart file in subdomain mdu-

T
files. D-Flow FM automatically fills in the correct names, when partition an mdu-file to subdo-
main mdu-files (see section 8.4.2), in the following way:
For Method 1 When <mduname_YYMMDD_HHMMSS_rst.nc> is filled in RestartFile of the orig-
inal mdu-file, partition this mdu-file gives subdomain mdu-files with RestartFile as
<mduname_000X_YYMMDD_HHMMSS_rst.nc> for each subdomain <000X>.
AF
For Method 2 If the string word "merged" is contained in the name of RestartFile in the original
mdu-file, then this file name is kept to all the subdomain mdu-files after partitioning.

It is also possible to use a map file as a restart file, following the above approaches. Notice
that in this case, one needs to specify the RestartDateTime in mdu-file as well. However,
we strongly recommend to use <_rst.nc> file instead of a map file.

8.9 Frequently asked questions

This chapter aims to help you with common questions that may arise while using D-Flow FM.
DR

1 Question
My model does not run/crashes. What’s wrong?
Answer
The diagnostics file is the starting point for finding out what went wrong. See section F.1
for a detailed description of the contents of this file, and the order of model run output.
Globally, ask yourself the following questions:
⋄ Was the mdu-file found?
⋄ If yes, was the model successfully loaded? Common mistakes are missing boundary
or meteorological forcings file.
⋄ If yes, was the time loop successfully started? Possible errors are non-writable output
files.
⋄ If yes, does the dia file contain any messages from during the time loop? Possible
errors are solver convergence errors.
⋄ If not, did the run end successfully?
2 Question
I get a warning that my network is non-orthogonal. Can I loosen the orthogonality tresh-
old?
Answer
Unfortunately, no. Orthogonality is very important for accuracy: advised orthogonality val-
ues for your grid are around 0.01, preferrably lower. The current treshold is already very
high at a value of 0.5. Use Grid Editor to improve your grid orthogonality.

3 Question
When running a computation with a batch script on Linux, should I call DIMR or dflowfm?
Answer
When running D-Flow FM online in combination with for example D-RTC, you have to

Deltares 140 of 562

 Running a model

run via DIMR. When running a standalone D-Flow FM computation, you can also choose
dflowfm. Deltares aims on one method for running computations and that is via DIMR.
But not all D-Flow FM functionality is yet available via DIMR, which involves functionality
for partitioning a model (Section 8.4.2)

T
AF
DR

Deltares 141 of 562

 9 Visualize results

9.1 Introduction
A model run will produce two types of output:
1 a graph or history (<∗.his>-file) for a specific quantity on a location
2 a map (<∗.map>-file) for a specific quantity

Both are stored in files within the project, as described in section 8.6.

T
D-Flow FM provides basic visualization of the model and the model results. Advanced and
tailor-made visualization is possible by the export of the his- and/or map-files, and inspection
with dedicated visualization applications. Some are provided and described below.

9.2
AF Visualization with the User Interface
When your model run has finished, a new folder called “Output” has appeared at the bottom
of the attributes of your model in the Map window. Inside this folder, all output quantities of
the his-, and map-files can be found, as well as a folder called “States”, in which you find
all restart files written during the model run. Output folders have also appeared in the Map
window; “Output (map)” and “Output (his)”. Both the results of your map and his files can be
viewed in the central map by means of enabling the desired quantities from the Map window
(Figure 9.1).
DR

Figure 9.1: Example of setting output (in)visible in the Map window

The time navigator can be used to slide through the different time steps in the output files.
If your model is relatively large, the drawing performance of the interface can be improved

Deltares 142 of 562

 Visualize results

dramatically by enabling QuadTree visualizations in the properties window of the layer you
want to visualize. To this end, select the layer you want to visualize in the ...

9.3 Visualization with Delft3D-QUICKPLOT

The interface of the Delft3D-QUICKPLOT allows to open the netCDF output files from a D-
Flow FM simulation. In the interface you can select data fields, make a selection of time
steps, stations or specify a preferred figure presentation options. After selection of a certain
options you can visualize your data by using the “Quick View” button. To add another plot to
an existing figure the “Add to Plot” button should be used.

T
When plotting the map output files from a D-Flow FM simulation, by default the presentation
type “markers” will be selected. To smoothly visualize your results it is recommended to
change presentation type into “polygons” and then select the option “Fill Polygons” (see the
example on the Figure 9.2).
AF
DR

Figure 9.2: Useful map visualization options in the Delft3D-QUICKPLOT

See the Delft3D-QUICKPLOT User Manual for full details and a description of the routines
and their use.

9.4 Visualization with Matlab

In the OpenEarthTools you can find a lot of Matlab scripts and functions that allow you to load,
process and visualize your D-Flow FM output. For detailed guidance on getting started and
using these tools effectively, visit https://publicwiki.deltares.nl/display/OET/MATLAB.

9.5 Visualization with Python

History-files can be easily visualized using xarray (https://docs.xarray.dev/en/stable/). Simi-
larly, map-files can be visualized using xugrid (https://deltares.github.io/xugrid/). Xugrid is a
UGRID wrapper around xarray that exposes many plotting options and processing options

Deltares 143 of 562

 Visualize results

like coordinate transformation, re-indexing, rasterizing and regridding. If you want to do more
advanced map-file visualization like horizontal and vertical (2DV cross section) slicing you
can use dfm_tools (https://deltares.github.io/dfm_tools/), this package uses xarray and xugrid
where possible and adds several extra features to read, process and visualize the history- and
map-files of D-Flow FM. It can also works with multiple partitions and with older D-Flow FM
mapformats.

T
AF
DR

Deltares 144 of 562

10 3D modelling in D-Flow FM
In D-Flow FM 3D modelling is summarized as follows:
⋄ 3D hydrodynamic modelling is fully available in D-Flow FM, including transport of salinity,
temperature and conservative tracers.
⋄ However, 3D sediment modelling is still β functionality.
⋄ In D-Flow FM σ -co-ordinates, z-co-ordinates and z-σ -co-ordinates are possible in the
vertical. For deep water applications (roughly deeper than one kilometer) z-σ -co-ordinates
are preferred. In this way, relatively thin σ -layers of a few meters near the surface can be

T
combined with z-layers of an increasing thickness in deeper parts.
⋄ The GUI for 3D modelling is incomplete yet. Therefore, some keywords for 3D mod-
elling can be set via the GUI, while others have to be edited manually; see section sec-
tion 7.4.16.
⋄ For preprocessing, processing and postprocessing of 3D modelling a detailed workflow
AF description is available, see the tutorials in section 23.2. Preprocessing is supported.
For processing the standard approach of DIMR is available. Postprocessing of 3D model
results is supported with QUICKPLOT.
⋄ In general, D-Flow FM has been developed for coastal applications and therefore focusses
on processes in relatively shallow areas of up to a few hundred meters deep. For such
applications D-Flow FM performs adequately. However, sometimes D-Flow FM models
also contain kilometers deep oceanic areas. D-Flow FM has shown to compute adequate
model results in some of these applications, but this cannot be guaranteed. For example,
checkerboarding of model results could occur. More research in oceanic waters is needed.

Note: In case of 3D modelling, for one numerical keyword the default value isn’t optimal yet.
DR

So, please read section section 10.8.1 in order to change this keyword manually.

10.1 Introduction to vertical layering approaches

In many rivers the flow is well mixed and can be described efficiently in 2D using the loga-
rithmic flow profile. In oceans, seas, estuaries and lakes, stratified flows may occur, the flow
profile may not be logarithmic anymore and 3D modelling is required. Vertical gradients in
velocity, salinity and temperature have to be computed accurately. Especially in stratified sys-
tems this might be a challenge. High gradients may occur around pycnoclines, and near the
surface and near the bed. Fortunately, there is no need to resolve the bed boundary layer
because it is fully developed in most cases. The law of the wall is then well applicable to
include the effect of bottom friction.

In the vertical, two approaches are widely used: the so-called σ -co-ordinate (terrain-following)
and z-co-ordinate (geopotential) models. A σ -co-ordinate model (Phillips, 1957) has a fixed
number of layers everywhere and the layer interfaces move in time with the varying water level,
while a z-co-ordinate model uses layer interfaces at fixed vertical positions. Consequently, in
case of z-layers the number of layers at a location varies with its water depth, see Figure 10.2.
In D-Flow FM both layer approaches have been implemented, including a combination of σ -
and z-layers (see section 10.4).

The distribution of the relative layer thickness can be done in a non-uniform way. This allows
for more resolution in the zones of interest such as the near surface area (important for e.g.
wind-driven flows, heat exchange with the atmosphere) and the near bed area (sediment
transport). Please note that in D-Flow FM, unlike Delft3D-FLOW, the σ coordinate is equal to
zero on the bed is 1 on the water surface.

Deltares 145 of 562

 3D modelling in D-Flow FM

T
Figure 10.1: Example of σ -model (left) and Z -model (right).

Although the σ -grid is boundary fitted in the vertical, it will not always have enough resolution
around the pycnocline. The co-ordinate lines intersect the density interfaces that may give sig-
AF
nificant errors in the approximation of strictly horizontal density gradients (Leendertse, 1990;
Stelling and Van Kester, 1994). Therefore, Z -model was introduced in D-Flow FM for 3D sim-
ulations of weakly forced stratified water systems. The Z -model has horizontal co-ordinate
lines that are (nearly) parallel with density interfaces (isopycnals) in regions with steep bed
slopes. This is important to reduce artificial mixing of scalar properties such as salinity and
temperature. The Z -model is not boundary-fitted in the vertical. Then, the bed and free sur-
face is usually not a co-ordinate line and is represented as a staircase (zig-zag boundary). At
the free surface, this can give very small layers, which can be much smaller than the next (sec-
ond) layer from the top. This is a disadvantage for numerical modelling, which also holds for
the staircase pattern of z-layers near the surface. To circumvent this problem, a z-σ approach
DR

has been implemented as well in D-Flow FM (see section 10.4).

Figure 10.2: Vertical grid numbering, for a σ -model (left) and a z-coordinate model (right)

To switch to 3D simulations, the keyword Kmx=N has to be set with N the number of layers in
the vertical. When Kmx equals 0, then a 2D implementation is applied. When Kmx equals 1,
then a 3D computation with one layer is applied, which is very similar to 2D modelling. The
main difference is that the specified 2D bed friction coefficient is first translated to a roughness
height z0 that is used in the computation of the shear velocity u∗ in the lowest layer of a 3D
model using the logarithmic profile assumption.

Via keyword LayerType one can choose between σ -co-ordinate (LayerType=1) or z-co-
ordinates (LayerType=2).

Via keyword StretchType non-uniform layers can be specified:

Deltares 146 of 562

 3D modelling in D-Flow FM

1=user defined
2=exponential

If StretchType is not specified, a uniform layer distribution is applied.

Via keyword StretchCoef the layer thicknesses (in percentages) are prescribed. An ex-
ample for option StretchType=1 might be:

StretchCoef=4.0, 5.9, 8.7, 12.7, 18.7, 18.7, 12.7, 8.7, 5.9, 4.0

T
and for option StretchType=2:

StretchCoef=stretching level, coef1, coef2

where stretching level determines the vertical position from which the layer interfaces
AF are computed and coef1 and coef2 are the two factors determining how the layers grow,
below and above the stretching level, respectively. The stretching level is a frac-
tion [0,...,1] between the bed level (=0.0) and the water surface (=1.0). For example in case
of StretchCoef=0.3, 1.1, 1.2, then the layer thicknesses are computed starting at
30% from the bed level, increase towards the bed level by 10% and increase towards the free
surface by 20%, for which the number of layers is defined by keyword Kmx.

10.2 σ -layer modelling

For river models, σ -models are commonly applied, as they have the advantage that the grid
nicely follows the topography. An additional advange of σ -models is that all cells have neigh-
DR

bours, allowing for relatively straightforward discretizations. However, disadvantages are that
1) for steeper topography, e.g. near groynes and banks, the σ -transformation suffers from
the so-called hydrostatic inconsistency (see the next section) and 2) that excessive vertical
resolution is applied in shallower areas, e.g. on the floodplains, reducing the efficiency of the
model.

10.3 Z-layer modelling

For temperature computations, the part of the water column just below the lowest thermocline
up to the free surface is of interest. Not knowing its position in advance, this top part of the
water column can best be resolved by a uniform resolution in the vertical via keyword DzTop
(in group [Geometry]). The vertical grid is uniform above a level called DzTopUniAboveZ
and extends to the top layer level called FloorLevTopLay. This level is called a floor
level because only the floor level of the top layer can be specified. (The ceiling of the top
layer is the water level). Below the level DzTopUniAboveZ the layer size may grow in
downward direction. To have layers growing in thickness downward e.g. by a factor 1.1, set
keyword SigmaGrowthFactor=1.1. The total number of layers is recounted based upon
the deepest cell in the model.

In case of a z-co-ordinate model we have the following additional keywords:

ZLayTop =
ZLayBot =

to specify the maximum and the minimum grid layer interface, respectively.

The advantage of z-layers is that no horizontal gradients are computed when only vertical
gradients exist. However, at the bed, the z-layer thickness may vary. This in turn may cause

Deltares 147 of 562

 3D modelling in D-Flow FM

a σ -like representation at the bed, with adverse effects on horizontal flows. Even the smallest
error in horizontal baroclinic or diffusivity terms will generate horizontal flow, that will imme-
diately lead to vertical velocities. Vertical velocities are always overestimated in hydrostatic
models because there is no counteracting force in absence of the vertical momentum equa-
tion. Any vertical velocity may pump up saline water for free, generating horizontal baroclinic
pressure forces, and more flow, and will eventually mix up the whole vertical. This mechanism
will prevail especially in stagnant water, as in lakes. To prevent this behaviour in z-layers,
specify by KeepZLayeringAtBed = 1 (in group [Numerics]). This will increase the layer
thickness at the bed such that all horizontally neighbouring cells have the same layer thick-
ness. The volume of the bed cell is overestimated. This is the default setting.

T
If a value of zero is specified, the floor level of the lowest z-layer is equal to the bed level. The
volume of the bed cell is represented more correctly. This may, however, lead to a very thin
bed layer if the bed level is just below the ceiling level of the bed layer. To circumvent this,
the ceiling level of the bed layer may be set halfway in between the bed level and the ceiling
AF level off the upper neighbour (conform setting ZTBML = #Y# as available in Delft3D-FLOW,
see also Platzek et al. (2012)). The bed volume is represented correctly, and some error is
introduced related to sigma behaviour of the bed layer. This is the preferred setting in non-
stagnant flows, specified by KeepZLayeringAtBed = 2. This option only works fine in
combination with NumTopSig >= 2. This prevents the first interface above the bed from
alternating ("flip/flop") behaviour at low water depth.

In z-layer models, staircases are introduced at the lower layers if the bed levels are varying.
This will affect the reconstruction of cell centre velocities, that play a role in the Coriolis terms,
advection terms and in estimates of bed friction in morphology. In the examples shown below,
the cell centre velocity in z will be erroneously reduced to half of the cell centre velocity in
DR

σ -models. To resolve this problem, one would have to implement a feature similar to cut-cells
(as applied in the horizontal plane), in the vertical. As a first step in this direction, we have
implemented a very simple first solution, namely copying the primitive velocity of the bed flow
link down to its downstairs neighbours. This velocity is then used in computing cell centre
velocities. In this way, the cell centre velocities in z layers will be almost the same as in
sigma layers. This option can be switched on by specifying Zlayercenterbedvel = 1
(in group [Numerics]).

10.4 Z-σ -layer modelling

In z-layer models, the top layer may become very thin. This may give rise to poor vertical grid
smoothness. To circumvent this, one could apply several layers in σ -coordinates near the free
-surface level. To set e.g. the top six layers to be of σ -type, set NumTopSig=6 (in group
[Geometry]), see subplot c) of Figure 10.3.

By default, the number of σ -layers on top of the z-layers, NumTopSig, is kept uniform over
the entire model. Sometimes this may be less desirable, because all NumTopSig σ -layers
will remain in the model up to the highest bed level, e.g. in an upstream river part of a
model. If one wants to gradually decrease the number of σ -layers for increased bed levels,
one can specify NumTopSigUniform = 0 (in group [Geometry]). Now, as bed levels be-
come higher, the number of layers decreases (similar to a z-layer model), as in subplot d) of
Figure 10.3. Not specifying this parameter will yield its default value of NumTopSigUniform
= 1 and keep the number of top σ -layers uniform over the model. These concepts are illus-
trated in Figure 10.3 for a grid with kmx = 15 layers. For completeness, also the standard σ -
and z-layer approaches are shown. The two different z-σ grids shown in subplots c) and d)
(with NumTopSigUniform = 1 and NumTopSigUniform = 0, respectively) show a
situation where NumTopSig=6. This results in the fact that the bottom 9 of the 15 layers are
z-layers and the top 6 layers are of σ -type. The difference between NumTopSigUniform

Deltares 148 of 562

 3D modelling in D-Flow FM

= 1 and NumTopSigUniform = 0 - in subplots c) and d) - then lies in the fact that the
bottom σ -layers in the area where the bed level is above the z-σ interface vanish. In this way,
the number of σ -layers in subplot d) is reduced from 6 to 2 in the shallow part of the domain.
This option can be used for avoiding excessive vertical resolution in shallow areas.

T
AF
DR

Figure 10.3: Illustration of the different layering concepts of D-Flow FM: a) σ -layering; b)
z-layering; c) z-σ -layering with NumTopSigUniform = 1; d) z-σ -layering
with NumTopSigUniform = 0.

Preferably, one should choose the number of σ -layers NumTopSig in the top section of the
grid, such that the vertical variation of the water level (e.g. the tidal range) is entirely within
the σ part of the water column. In Figure 10.3, this would mean that the variation of the free
surface occurs fully above the red dotted line that indicates the z-σ interface.

To compute the z-σ interface position the following formula is appied:

ZSigmaInterface = FloorLevToplay - DzTop*(NumTopSig-1)

10.5 Boundary conditions in 3D

Boundary conditions for 3D models can be prescribed in the same way as for 2D models, i.e.
water level, discharge or depth-averaged velocity boundary conditions can be prescribed for
hydrodynamics. Similarly, boundary conditions for transport processes such as temperature
or salinity can also be provided in a depth-averaged fashion. However, in certain flow situa-
tions, such as for stratified flows, the boundary conditions need to vary over the vertical. This
is also possible in D-Flow FM.

Deltares 149 of 562

 3D modelling in D-Flow FM

In section 7.4.8 a description was provided of how to specify boundary conditions in the User
Interface. This also included an example of 3D boundary conditions. Vertically-varying bound-
ary conditions can be prescribed for both hydrodynamic quantities (flow velocity, discharge)
and for transport quantities (e.g. temperature, salinity, sediment fractions, tracers). Possible
options are to set the boundary conditions using a step/block function or using linear variation.
Additionally, the vertical positions at which boundary values are provided can be specified in
different ways, e.g. using a z -coordinate in the reference frame of the model, using a position
relative to the bed or free surface, or using a percentage/fraction of the total water depth at the
boundary. A more detailed list of all possible options for prescribing 3D boundary conditions
can be found in section C.5.

T
10.6 Turbulence modelling
D-Flow FM solves the shallow water equations for incompressible flow. Usually the grid (hori-
zontal and/or vertical) is too coarse and the time step too large to resolve the turbulent scales
AF of motion. The turbulent processes are “sub-grid”. The primitive variables are space- and
time-averaged quantities. Filtering the equations leads to the need for appropriate closure
assumptions.

For 3D shallow water flow the stress and diffusion tensor are an-isotropic. The horizontal eddy
viscosity coefficient νH and eddy diffusivity coefficient DH are much larger than the vertical
coefficients νV and DV , i.e. νH ≫ νV and DH ≫ DV . The horizontal coefficients are
assumed to be a superposition of three parts:
1 a part due to molecular viscosity.
2 a part due to “2D-turbulence”,
DR

3 a part due to “3D-turbulence” see Uittenbogaard et al. (1992) and

The 2D part is associated with the contribution of horizontal motions and forcings that cannot
be resolved (“sub-grid scale turbulence”) by the horizontal grid (Reynolds averaged or eddy
resolving computations). The 3D part is referred to as the three-dimensional turbulence and
is computed following one of the turbulence closure models, described in this section. For
2D depth-averaged simulations, the horizontal eddy viscosity and eddy diffusivity coefficient
should also contain a contribution due to the vertical variation of the horizontal flow (Taylor
shear dispersion).

back back
The background horizontal viscosity coefficient νH and eddy diffusivity coefficient DH
(constant or space-varying) can be specified in the D-Flow FM GUI and in the related MDU
file.

In D-Flow FM for horizontal viscosity the so-called Smagorinsky model is the default approach,
yielding a space and time varying horizontal viscosity.

The horizontal eddy coefficients are typically an order of magnitude larger than the vertical
coefficients determined by the turbulence closure model.

In D-Flow FM, two two-equation turbulence closure models have been implemented to deter-
mine the vertical eddy viscosity (νV ) and vertical eddy diffusivity (DV ):
1 k -ε turbulence closure model.
2 k -τ turbulence closure model (in β -version).

The k -τ model is a mathematical variant of the k -ε model, Dijkstra (2014). Both models solve
equations for production, dissipation and transport of turbulent kinetic energy k . In the k -ε

Deltares 150 of 562

 3D modelling in D-Flow FM

model the dissipation rate of turbulent kinetic energy ε, is modeled, whereas in the k -τ model
the dissipation timescale τ is modeled.

Both models are based on the so-called eddy viscosity concept of Kolmogorov (1942) and
Prandtl (1945).

A brief description of each of these turbulence closure model will be given further on in this
section, for more details we refer to Uittenbogaard et al. (1992). The k -ε model has been
used in tidal simulations by Baumert and Radach (1992) and Davies and Gerritsen (1994), for
stratified flow of a river plume by Postma et al. (1999) and for the evolution of a thermocline

T
by Burchard and Baumert (1995).

For strongly stratified flows it is important to introduce suitably chosen constant ambient (back-
ground) mixing coefficients, because the mixing coefficients computed by turbulence models
with shear production only, reduce to zero. In the latter situation the vertical layers are com-
AF
pletely de-coupled (frictionless). Disturbances are hardly damped and also the erosion of the
vertical stratification is reduced to molecular diffusion.

Based on our experience with highly stratified flows we suggest applying an ambient or back-
ground vertical eddy viscosity in the order of 10−4 m2 /s for the vertical exchange of mo-
mentum. This value corresponds with field measurements in the Rotterdam Waterway, The
Netherlands.

Eddy diffusivity
The vertical eddy diffusivity is a scaled form of the eddy viscosity according to:
DR

ν3D
D3D = . (10.1)
σc

Parameter σc is the Prandtl-Schmidt number. Its numerical value depends on the constituent
c.

In Delft3D-FLOW the following settings of σc are used:

⋄ In all cases, regardless the turbulence closure model, σc = 0.7 for the transport of heat,
salinity, and tracer concentrations. For suspended sediment concentrations in online sed-
iment transport computations, σc = 1.0.
⋄ For the transport of turbulent kinetic energy k in the k -L model and k -ε model σc = 1.0,
and for the transport of turbulent kinetic energy dissipation ε in the k -ε model σc = 1.3.

In the mathematical formulation, the fluxes are instantaneously influenced by changes in the
vertical gradients of velocity and density. A physical adjustment time of the turbulence to the
variations of the vertical gradients, is not taken into account. The fluxes are not a monotone
function of the gradients. For the transport equation of heat, for small temperature gradients
the heat flux increases when the temperature gradient increases but for large temperature
gradients the heat flux decreases because the vertical eddy diffusivity is damped. For large
values of the density gradients and small values of the velocity gradients, the vertical diffusion
equation becomes mathematically ill-posed Barenblatt et al. (1993), and the computed vertical
profiles may become discontinuous (stepwise). The number of “steps” is dependent on the
vertical grid.

The numerical scheme for the vertical advection of heat and salt (central differences) may
introduce small vertical oscillations. This computational noise may enhance the turbulent

Deltares 151 of 562

 3D modelling in D-Flow FM

mixing. D-Flow FM has a vertical filtering technique to remove this noise and to reduce the
undesirable mixing. For more details, see section 4.2.4.

In strongly-stratified flows, the turbulent eddy viscosity at the interface reduces to zero and
the vertical mixing reduces to molecular diffusion. To account for the vertical mixing induced
by shearing and breaking of short and random internal gravity waves, we suggest to apply an
ambient eddy diffusivity in the order of 10−4 to 10−5 m2 /s dependent on the Prandtl-Schmidt
number. For stable stratified flows, the eddy diffusivity in D-Flow FM may also be based on
the Ozmidov length scale Loz , as specified by the user, and the Brunt-Väisälä frequency of
internal waves. Then, the vertical eddy diffusivity DV is defined as:

T
s
g ∂ρ
DV = D3D + 0.2L2oz − . (10.2)
AF ρ ∂z

where D3D is the vertical eddy diffusivity component computed by the turbulence model.
Loz represents the Ozmidov length scale and the term ρg ∂ρ ∂z
reflects the density gradient in
the fluid, driven by the gravitational constant g and density ρ. For a detailed description of
the turbulence closure models as applied in D-Flow FM and Delft3D-FLOW we refer to Rodi
(1984) and Uittenbogaard et al. (1992).

10.6.1 k -ε turbulence model

In the k -ε turbulence model, transport equations must be solved for both the turbulent kinetic
energy k and for the energy dissipation ε. The mixing length L is then determined from ε and
DR

k according to:
√
k k
L = cD . (10.3)
ε

In the transport equations, the following two assumptions are made:

⋄ The production, buoyancy, and dissipation terms are the dominating terms.
⋄ The horizontal length scales are larger than the vertical ones (shallow water, boundary
layer type of flows).

Because of the first assumption, the conservation of the turbulent quantities is less important
and the transport equation is implemented in a non-conservation form.

The transport equations for k and ε are non-linearly coupled by means of their eddy diffusivity
Dk , Dε and the dissipation terms. The transport equations for k and ε are given by:
∂k ∂k ∂k ω ∂k
+u +v + =
∂t ∂x ∂y ζ − zb ∂σ
 
1 ∂ ∂k
+ Dk + Pk + Pkw + Bk − ε, (10.4)
(ζ − zb )2 ∂σ ∂σ

∂ε ∂ε ∂ε ω ∂ε
+u +v + =
∂t ∂x ∂y ζ − zb ∂σ
ε2
 
1 ∂ ∂ε
D ε + Pε + Pεw + Bε − c2ε . (10.5)
(ζ − zb )2 ∂σ ∂σ k

Deltares 152 of 562

 3D modelling in D-Flow FM

with
νmol ν3D ν3D
Dk = + and Dε = (10.6)
σmol σk σε

In the production term Pk of turbulent kinetic energy, the horizontal gradients of the horizontal
velocity and all the gradients of the vertical velocities are neglected. The production term is
given by:
" 2  2 #
1 ∂u ∂v

T
Pk = ν3D + . (10.7)
(ζ − zb )2 ∂σ ∂σ

For small-scale applications (e.g. simulation of laboratory flume), you can switch on a more
extended production term Pk of turbulent kinetic energy (option “partial slip”, rough side wall)
AF
given by:
"
1
(
∂u
2  2 )#
∂v
Pk = 2ν3D + +
2 (ζ − zb )2 ∂σ ∂σ
"  2  2 #
2 
∂u 1 ∂u ∂v ∂v
+ 2ν3D + + + . (10.8)
∂x 2 ∂y ∂x ∂y

In this expression, ν3D is the vertical eddy viscosity, prescribed by Equation (10.15). In Equa-
DR

tion (10.7) and Equation (10.8) it has been assumed that the gradients of the vertical velocity
w can be neglected with respect to the gradients of the horizontal velocity components u and
v . The horizontal and vertical (σ -grid) curvature of the grid has also been neglected.

The turbulent energy production due to wave action is given by Pkw , but has not been im-
plemented yet in D-Flow FM: Wave forcing in 3D models is being prepared for an upcoming
release.

Near the closed walls the normal derivative of the tangential velocity is determined with the
law of the wall:
∂u u∗
= . (10.9)
∂y κy

In stratified flows, turbulent kinetic energy is converted into potential energy. This is repre-
sented by a buoyancy flux Bk defined by:

ν3D g ∂ρ
Bk = (10.10)
ρσρ h ∂σ
with the Prandtl-Schmidt number σρ = 0.7 for salinity and temperature and σρ = 1.0 for
suspended sediments.

The production term Pε and the buoyancy flux Bε are defined by:
ε
Pε = c1ε Pk , (10.11)
k
ε
Bε = c3ε Bk , (10.12)
k

Deltares 153 of 562

 3D modelling in D-Flow FM

with L prescribed by Equation (10.3) and the calibration constants by (Rodi, 1984):

c1ε = 1.44, (10.13)

c2ε = 1.92 (10.14)

In D-Flow FM in the ε-equation for stable stratification the buoyancy flux is switched off, so
c3ε = 0.0 and for unstable stratification the buoyancy flux is switched on c3ε = c1ε = 1.44.

The energy production and energy dissipation due to waves, the terms Pkw and Pεw in Equa-

T
tion (10.4) and Equation (10.5), have not been implemented yet in D-Flow FM: Wave forcing
in 3D models is being prepared for an upcoming release.

The coefficients of the 3D k -ε turbulence closure model as implemented in D-Flow FM are

not the same as in the depth-averaged k -ε turbulence closure model (Rodi, 1984), therefore
AF
for depth-averaged simulations, the k -ε turbulence closure model is not available for you.

The vertical eddy viscosity ν3D is determined by:

√ k2
ν3D = c′µ L k = cµ , (10.15)
ε
with:

cµ = cD c′µ . (10.16)
DR

To solve the transport equation, boundary conditions must be specified. A local equilibrium of
production and dissipation of kinetic energy is assumed at the bed which leads to the following
Dirichlet boundary condition:

u2
k|σ=−1 = √∗b . (10.17)
cµ

The friction velocity u∗b at the bed is determined from the magnitude of the velocity in the
grid point nearest to the bed, under the assumption of a logarithmic velocity profile. The bed
roughness (roughness length) may be enhanced by the presence of wind generated short
crested waves.

In case of wind forcing, a similar Dirichlet boundary condition is prescribed for the turbulent
kinetic energy k at the free surface:

u2
k|σ=0 = √∗s . (10.18)
cµ

In the absence of wind, the turbulent kinetic energy k at the surface is set to zero.

At open boundaries, the turbulent energy k is computed using the equation for k without hor-
izontal advection. For a logarithmic velocity profile this will approximately lead to the following
linear distribution based on the shear-stress at the bed and at the free surface:
   
1 2 z − zb 2 z − zb
k (z) = √ u 1− + u∗s . (10.19)
cµ ∗b ζ − zb ζ − zb

Deltares 154 of 562

 3D modelling in D-Flow FM

For ε the bed boundary condition reads:

∂ε (εb+1 − εb ) u3∗
= =
2 (10.20)
∂z ∆zb κ ∆zb
+ 9z0
2

The k -ε turbulence model was successfully applied for the simulation of stratified flow in the
Hong Kong waters (Postma et al., 1999) and verified for the seasonal evolution of the thermo-
cline (Burchard and Baumert, 1995).

T
10.6.2 k -τ turbulence model
The k -τ turbulence model is derived by Speziale et al. (1992) as a transformation of the
ε-equation of the k -ε turbulence model where the variable τ models a typical time-scale of
turbulent eddies [s].
AF The k -τ turbulence model used in D-Flow FM deviates from the equation of Speziale et al.
(1992) at a few points, to derive their k -τ model they used a different version of the k -ε model
and the most important difference is that they do not include buoyancy in their model.

The transport equations for k and τ used in D-Flow FM read (see for a derivation Dijkstra
(2014)):

∂k ∂k ∂k ω ∂k
+u +v + =
∂t ∂x ∂y ζ − zb ∂σ
DR

 
1 ∂ ∂k k
2 Dk + Pk + Pkw + Bk − , (10.21)
(ζ − zb ) ∂σ ∂σ τ

∂τ ∂τ ∂τ ω ∂τ
+u +v + =
∂t ∂x ∂y ζ − zb ∂σ
     
1 ∂ ∂τ 2 ∂τ ∂k 2 ∂τ ∂τ τ ∂ 1 1 ∂k
Dτ + Dτ − Dτ − −
(ζ − zb )2 ∂σ ∂σ k ∂σ ∂σ τ ∂σ ∂σ k ∂σ σε σk ∂σ
τ τ
− (cε1 − 1)Pk − (cε3 − 1)Bk + cε2 − 1 (10.22)
k k
with
νmol ν3D ν3D
Dk = + and Dτ = . (10.23)
σmol σk στ

10.7 Fixed weirs for 3D modelling

As described in Section 12.1, in D-Flow FM two different approaches are applied to simulate
the energy losses by fixed weirs. First of all, a numerical approach has been implemented.
Then, a special discretization of the advective terms around the fixed weir is applied. Next to
the numerical approach, there is an empirical (subgrid) approach. Based on measurements
in flume laboratories empirical formulae can be derived in order to match the measurements
as accurately as possible. Two empirical formulae are available in D-Flow FM, namely the
so-called ’Villemonte’ and ’Tabellenboek’ approaches. The Villemonte approach is the default
option. For a detailed description of the fixed weirs we refer to Deltares (2025a, section 6.7.1–
6.7.4).

Deltares 155 of 562

 3D modelling in D-Flow FM

In case of 3D modelling, the Villemonte approach (fixedweirscheme=9) should be ap-

plied. This has been thoroughly tested. We remark that the other empirical approach - Tabel-
lenboek via (fixedweirscheme=8) - is also possible for 3D modelling, but this option has
been much less tested. The numerical option (fixedweirscheme=6) is not available for
3D modelling.

No special input is required for fixed weir modelling in case of 3D modelling. The fixed weir
input is identical for 2D and 3D modelling, which is described in detail in Appendix C.8.

T
10.8 3D modelling guidelines
When setting up 3D models, using one of the grid-layering approaches described in the pre-
vious sections, one should consider a number of aspects besides the aforementioned options
and keywords. In the following subsections these aspects will be explained.
AF
10.8.1 Non optimal default value in case of 3D modelling
In general, the default value of a keyword gives the best results; see for example Table A.1 and
Table A.2 with an extensive overview of keywords including its default value and its description.
However, there is one exception: the keyword for the vertical advection method in the transport
equation isn’t optimal. This involves keywords Vertadvtypsal and Vertadvtyptem.
Currently. Vertadvtypsal=Vertadvtyptem=6 is the default, which corresponds to a
higher-order upwind explicit approach. The reason for this is to obtain consistency with the
discretization of the vertical advection term in the momentum equations, for which the same
higher-order upwind explicit method is applied. In the momentum equation such an approach
is crucial to minimize checkerboarding of the model reuslts, which is achieved by applying
DR

the same advection discretization mehod in the horizontal and in the vertical. However, this
results into more numerical mixing in the vertical than needed.

The second-order central advection discretization leads to less numerical mixing in the vertical
and is a better approach. This is currently almost achieved by Vertadvtypsal=Vertadvtyptem=4.
Therefore, in 3D simulations a user is advised to manually change these keywords in the
MDU-file to the value of four; see also the description of these keywords in Table A.2. This
isn’t possible yet for tracer and sediment modelling, for which currently always the higher-
order upwind approach is applied. Noted that in the next release the default for the vertical
advection method for all substances will be changed to the second-order central discretization
method.

10.8.2 Number of layers

The number of layers that is to be recommended, depends on the application. From experi-
ence with Delft3D, which is based on structured grids, for many decades, salinity intrusion in
estuaries has been successfully computed with a relatively few number of layers. Quite often
ten layers have been applied. Nowadays, twenty layers seems to be more appropriate for 3D
modelling. For applications with a large range in water depth (e.g. including the continental
shelf), even more layers need to be applied, to accurately capture all vertical gradients in flow,
temperature and salinity.

Deltares 156 of 562

 3D modelling in D-Flow FM

10.8.3 Anti creep

In the σ co-ordinate system, the grid co-ordinate lines intersect the mostly horizontal density
interfaces. A well-known disadvantage of σ co-ordinates with standard numerical schemes is
that in areas of steep bed topography unphysical vertical mixing may occur due to hydrostatic
inconsistency (Haney, 1991). This is a result of erroneous computation of horizontal gradients
when vertical gradients exist. To suppress this, the anti-creep method by Stelling and Van
Kester (1994), first implemented in Delft3D, has also been implemented in D-Flow FM.

In D-Flow FM this can be switched on via keyword AntiCreep = 1. Noted that in z-

T
coordinates, the grid lines are by definition horizontal. Then, the anti creep option isn’t re-
quired.

10.8.4 Spurious oscillations in vertical velocity

AF In D-Flow FM unphysical oscillations can occur in 3D models. These oscillations are pri-
marily manifest themselves as a “checkerboard”-like pattern in the vertical velocities, which
can cause checkerboarding in the horizontal velocities as well. This might lead to unrealistic
model results. A high-order horizontal momentum filter is available to suppress these spuri-
ous oscillations. This filter is switched on via keyword HorizontalMomentumFilter=1.
A monitor function is available to check whether spurious oscillations occur in a model ap-
plication. This filter can be switched on via keyword CheckerboardMonitor=1. This is
illustrated in Figure 10.5.
DR

Figure 10.4: Illustration of spurious oscillations in horizontal currents near open bound-
aries

Figure 10.4 illustrates these patterns in the horizontal velocities near the open boundary with-
out the application of the filter. These patterns largely disappear with the application of the
filter.

Deltares 157 of 562

 3D modelling in D-Flow FM

T
AF Figure 10.5: Illustration of monitor for occurrence of spurious oscillations
DR

Deltares 158 of 562

 11 Boundary conditions in D-Flow FM

11.1 Hydrodynamics boundary conditions

In section 7.4.8, the boundary conditions are discussed from the viewpoint of the user inter-
face. In the user interface, the user can specify the locations at which particular boundary
conditions are to be imposed. Using section 7.4.8 as a backdrop, the present section dis-
cusses the underlying files and file formats and the way these are interpreted by the computa-
tional kernel. Three types of boundary conditions are discussed in this section, namely open
boundaries (in section 11.1.1) , vertical boundaries (in section 11.1.2) and closed boundaries

T
(in section 3.5).

Lateral discharges are a special type of input that also act like boundary conditions, and are
discussed in section 7.4.12.
AF
11.1.1 Open boundary conditions
The proper prescription of an open boundary condition along a certain (part of the) rim of the
grid can be achieved by considering four elements of the model:
1 a polyline file (extension .pli), containing the locations at which the boundary conditions
should be imposed,
2 a boundary conditions file (extension .bc), containing the actual forcing signals, such
as the time dependent information of the quantity under consideration and the physical
nature of the quantity itself,
3 an external forcing file (extension .ext), in which the connection is laid between the
polyline file and the boundary conditions file,
DR

4 the name of the external forcing file in the master definition file (extension .mdu).

These four elements are subsequently discussed in the following.

11.1.1.1 Forcing information

The <.bc>-file is used to store the actual boundary forcing signals. Multiple types of bound-
ary conditions can be prescribed, configured via the Quantity keywords. The following
subsections contain details for several types of flow boundaries.

The <.bc>-file may also contain the forcing signals for multiple boundary locations, con-
figured via the Name keyword. When boundary locations have been specified by a polyline
(locationFile in the <.ext> file), then the Name must refer to the polyline name, followed
by the polyline point number, e.g., Name = upstream_0001. When instead a nodeId
was used in the <.ext> file, the Name must be the same as that node id.

Deltares 159 of 562

 Boundary conditions in D-Flow FM

Water level
A water level signal is applied at the cell center of the virtual cell outside the grid (ghost cells
or mirror cells). Water levels can be imposed as a timeseries or as a harmonic signal. In
case of a harmonic signal, the period of the signal can be given as an astronomic component
acronym.

If a timeseries is applied to a the first support point of a polyline named arbitraryname,

prescribed in some polyline file, then the header of the bc-file is:

T
[forcing]
Name = arbitraryname_0001
Function = timeseries
Time-interpolation = linear
Quantity = time
Unit = minutes since YYYY-MM-DD
AF
Quantity
Unit
[two-column data]
=
=
waterlevelbnd
m

The data is to be inserted as a two-column array containing the time (in minutes) and the
water level itself (in meters w.r.t. the reference level). In case of harmonic components, the
header of the bc-file is:

[forcing]
Name = arbitraryname_0001
DR

Function = harmonic
Quantity = harmonic component
Unit = minutes
Quantity = waterlevelbnd amplitude
Unit = m
Quantity = waterlevelbnd phase
Unit = degrees
[three-column data]

The data is to be inserted as a three-column array containing the period (in minutes), the
amplitude (in meters) and the phase (in degrees). If the period is T minutes, the amplitude is
A meters and the phase is φ degrees, then the signal that is applied reads
h(t) = B + A cos(2πt/T − φ). (11.1)

The parameter B can be prescribed by an additional signal with a period specified equal to
0 minutes. As an example, the data series:

0.0 0.5 0.0

745.0 2.0 0.0

represents the signal h(t) = 0.5 + 2.0 cos(2πt/745), with the time t in minutes.

Discharge
A discharge boundary condition is applied at the face-center of the virtual boundary cell. For
this, the face-normal velocity is used in combination with the face-center water depth. The
face-based water depth in the evaluation of the flow area can optionally be set to a downwind

Deltares 160 of 562

 Boundary conditions in D-Flow FM

approximation (for an inflowing discharge boundary) with the option jbasqbnddownwindhs

= 1 We remark that jbasqbnddownwindhs = 0 is the default value.

Discharges can be imposed as a timeseries or as a harmonic signal. In case of a harmonic

signal, the period of the signal can be given as an astronomic component acronym.

If a timeseries is applied to a the first support point of a polyline named arbitraryname,

prescribed in some polyline file, then the header of the bc-file is:

T
[forcing]
Name = arbitraryname_0001
Function = timeseries
Time-interpolation = linear
Quantity = time
Unit = minutes since YYYY-MM-DD
Quantity = dischargebnd
AF
Unit
[two-column data]
= m3/s

The data is to be inserted as a two-column array containing the time (in minutes) and the
water level itself (in meters w.r.t. the reference level). In case of harmonic components, the
header of the bc-file is:

[forcing]
Name = arbitraryname_0001
Function = harmonic
DR

Quantity = harmonic component

Unit = minutes
Quantity = dischargebnd amplitude
Unit = m3/s
Quantity = dischargebnd phase
Unit = degrees
[three-column data]

The data is to be inserted as a three-column array containing the period (in minutes), the
amplitude (in cubic meters per second) and the phase (in degrees).

Velocity
A velocity boundary condition is applied at the face-center of the virtual boundary cell. Values
provided are interpreted as face-normal velocities. Velocities can be imposed as a timeseries
or as a harmonic signal. In case of a harmonic signal, the period of the signal can be given
as an astronomic component acronym.

If a timeseries is applied to a the first support point of a polyline named arbitraryname,

prescribed in some polyline file, then the header of the bc-file is:

[forcing]
Name = arbitraryname_0001
Function = timeseries
Time-interpolation = linear
Quantity = time
Unit = minutes since YYYY-MM-DD
Quantity = velocitybnd
Unit = m/s
[two-column data]

Deltares 161 of 562

 Boundary conditions in D-Flow FM

The data is to be inserted as a two-column array containing the time (in minutes) and the
water level itself (in meters w.r.t. the reference level). In case of harmonic components, the
header of the bc-file is:

[forcing]
Name = arbitraryname_0001
Function = harmonic
Quantity = harmonic component
Unit = minutes
Quantity = velocitybnd amplitude
Unit = m/s

T
Quantity = velocitybnd phase
Unit = degrees
[three-column data]

The data is to be inserted as a three-column array containing the period (in minutes), the
AF
amplitude (in meters per second) and the phase (in degrees).

Water level gradient

Besides the option to prescribe actual water levels as a boundary condition, D-Flow FM facil-
itates the prescription of water level gradients. Such a Neumann-type boundary condition for
the water level can be assigned through the keyword neumannbnd. The value of the water
level gradient is applied at the face-center.

Water level gradients can be imposed as a timeseries or as a harmonic signal. In case of a

DR

harmonic signal, the period of the signal can be given as an astronomic component acronym.
If a timeseries is applied to a the first support point of a polyline named arbitraryname,
prescribed in some polyline file, then the header of the bc-file is:

[forcing]
Name = arbitraryname_0001
Function = timeseries
Time-interpolation = linear
Quantity = time
Unit = minutes since YYYY-MM-DD
Quantity = neumannbnd
Unit = -
[two-column data]

The data is to be inserted as a two-column array containing the time (in minutes) and the
water level itself (in meters w.r.t. the reference level). In case of harmonic components, the
header of the bc-file is:

[forcing]
Name = arbitraryname_0001
Function = harmonic
Quantity = harmonic component
Unit = minutes
Quantity = neumannbnd amplitude
Unit = -
Quantity = neumannbnd phase
Unit = degrees
[three-column data]

Deltares 162 of 562

 Boundary conditions in D-Flow FM

The data is to be inserted as a three-column array containing the period (in minutes), the
amplitude (in meters per second) and the phase (in degrees). The water level gradient is
interpreted positive in the outward-normal direction.

Riemann invariant
At a Riemann boundary we do not allow any outgoing perturbation with respect to some
reference boundary state to reflect back from the boundary. This is achieved by prescribing
the incoming Riemann invariant. Using √ the convention of a positive inward normal at the
boundary, this can be put as ub + 2 gHb , with ub the velocity at the boundary and Hb the

T
total water depth at the boundary. In this expression, we take the boundary values ub and Hb
as the reference boundary state. While applying Riemann boundaries, directional effects are
disregarded.

Using linearization and the assumption of a flow field that is initially at rest, the Riemann
AF
boundary is rewritten such that is takes the form:
s
H
ζb = 2ζi − u − ζ0 (11.2)
g
with
ζb the surface level elevation at the boundary,
ζi the water level of the perpendicularly incoming wave at the boundary,
H the total water depth,
g the gravitational acceleration,
u
DR
the flow velocity (positive inward) and
ζ0 the initial water level elevation.

The user specifies as boundary signal ζi , the water level of the perpendicularly incoming
wave at the boundary. Formulated in this way, the incoming wave height is independent of
local bathymetry.
q
Following linear wave theory, one finds u Hg
for a propagating wave. One will obtain a water
level at the boundary of when there are no waves travelling from inside the model back to the
boundary.

Example
As an example, a simple uniform channel with two Riemann boundaries, with 1 m amplitude
on the left and 0 m on the right will show a 1 m amplitude wave travelling from left to right. At
the right side, the wave passes the boundary with minor reflection only. Practically no waves
travel from right to left since at the right boundary no incoming wave amplitude was specified.

The water level of the incoming wave for the Riemann boundary can be prescribed as a
timeseries or as a harmonic signal. In case of a harmonic signal, the period of the signal can
be given as an astronomic component, (e.g. M2 ), or as a period in minutes, amplitude in m
and phase in degrees. If a timeseries is applied to the first support point of a polyline named
arbitraryname, prescribed in some polyline file, then the header of the <bc>-file read:

[forcing]
Name = arbitraryname_0001
Function = timeseries
Time-interpolation = linear

Deltares 163 of 562

 Boundary conditions in D-Flow FM

Quantity = time
Unit = minutes since YYYY-MM-DD
Quantity = riemannbnd
Unit = m
[two-column data]

The data is to be inserted as a two-column array containing the time (in minutes) and the
water level for Riemann boundary (in meters). In case of harmonic components, the header
of the bc-file is:

T
[forcing]
Name = arbitraryname_0001
Function = harmonic
Quantity = harmonic component
Unit = minutes
AF
Quantity
Unit
Quantity
Unit
[three-column data]
=
=
=
=
riemannbnd amplitude
m
riemannbnd phase
degrees

The data is to be inserted as a three-column array containing the period (in minutes), the
amplitude (in meters per second) and the phase (in degrees).

Suppose, as an example, that we have:

DR

⋄ a flow domain with a bathymetry at a bed level equal to 0 m w.r.t. the reference level,
⋄ an initial water level equal to 10 m w.r.t. the reference level,
⋄ a local initial disturbance of the initial water level,
⋄ an initial flow field at rest and
⋄ that we aim to prevent reflections at the boundary.

In that case, it follows from Equation (11.2) that ζb = 10 m w.r.t. the reference level is to be
prescribed. Remark that this application only holds for small disturbances of ζ from ζb .

Discharge-water level dependency

If a relation between the discharge and the local water level is known on beforehand, then
this relation can be provided to the flow model as a table by means of the keyword qhtable.
This table, provides the water level ζ as a function of the computed discharge Q along the
entire polyline defining the boundary. Worded differently, only one relation is given for each
polyline. Note that this is opposite to other boundary types in which, for instance, a time series
is given for each support point of a polyline.

If a Qh-table is applied to a polyline named arbitraryname, prescribed in some polyline

file, then the header of the bc-file is:

[forcing]
Name = arbitraryname
Function = qhtable
Quantity = qhbnd discharge
Unit = m3/s
Quantity = qhbnd waterlevel
Unit = m
[two-column data]

Deltares 164 of 562

 Boundary conditions in D-Flow FM

The data is to be inserted as a two-column array containing the discharge (in cubic meters
per second) and the water level (in meters w.r.t. the reference level).

11.1.1.2 External forcings file

The external forcings file <.ext> collects all boundary condition information. The file for-
mat for boundaries is described in section C.6.2.1. It contains one or more [Boundary]
blocks, one for each boundary condition. Each block must specify the boundary type via the
quantity keyword. The previous section already listed some boundary quantity names.
Next, each block must specify the boundary location specification. This is either a polyline

T
file name, via the locationFile keyword, or a 1D network node id, via the nodeId key-
word. Finally, the actual forcing data file must be specified, via the forcingFile keyword.
Section 11.1.1.4 contains an example of this.

11.1.1.3 External forcings in model definition file

AF The final step in specifying boundary conditions, is referring to the <.ext> file in the <.mdu>
file. This is done via the keyword ExtForceFileNew under the MDU block [external
forcing].

11.1.1.4 Example
Recalling the four elementary actions from the beginning of section 11.1.1, the administration
in files can be illustrated by means of an example. Suppose, we have a channel that is
geometrically modelled by means of the grid shown in Figure 11.1. The domain is 10000 m
long and 500 m wide. The bottom left corner coincides with the origin of the geometrical frame
DR

of reference.

Figure 11.1: User Interface view of a simple channel covered by a straightforward Carte-
sian grid. Boundary conditions are prescribed at the left hand side and the
right hand size of the domain.

The domain shown in Figure 11.1 contains two boundaries: on the left hand, a discharge
boundary condition is present to present flow entering the domain, on the right hand, a water
level boundary condition is set. Having two boundaries, we have two polyline files, in this
example: left.pli and right.pli.

The contents of left.pli are:

boundaryleft
2 2
-80 -50
-80 550

whereas the contents of right.pli are:

Deltares 165 of 562

 Boundary conditions in D-Flow FM

boundaryright
2 2
10250 -50
10250 550

Notice that both polyline files contain the name of the polyline, namely boundaryleft
and boundaryright, respectively. In this example, both the polylines contain two support
points. For each of these support points, timeseries can be prescribed. In this example,
we restrict ourselves to homogeneous boundary conditions. This means that we have to

T
prescribe physical information for the first support points, i.e. for boundaryleft_0001
and boundaryright_0001.

The physical information should be provided in the bc-file. In this example, we use the follow-
ing bc-file:
AF
[forcing]
Name = boundaryleft_0001
Function = timeseries
Time-interpolation = linear
Quantity = time
Unit = minutes since 2001-01-01
Quantity = dischargebnd
Unit = m3/s
0.000000 2500.0
120.000000 3000.0
240.000000 2500.0
360.000000 2000.0
480.000000 2500.0
DR

600.000000 3000.0
720.000000 2500.0
840.000000 2000.0
960.000000 2500.0
1080.000000 3000.0
1200.000000 2500.0
1320.000000 2000.0
1440.000000 2500.0

[forcing]
Name = boundaryright_0001
Function = timeseries
Time-interpolation = linear
Quantity = time
Unit = minutes since 2001-01-01
Quantity = waterlevelbnd
Unit = m
0.000000 2.50
1440.000000 2.50

This file couples the timeseries for the discharge to the support point named boundaryleft_0001.
Likewise, the water level boundary, being constant in time, is coupled to the support point
named boundaryright_0001.

The final specification of the boundary conditions is wrapped up in the external forcing file,
with extension .ext. In this file, the connection is laid between the quantity of the bound-
ary condition, the name of the polyline file (in which the name of the polyline itself is given)
and the forcing file (in which the physical information is provided). In our example, the file
simplechannel.ext has the following contents:

[boundary]
quantity = dischargebnd

Deltares 166 of 562

 Boundary conditions in D-Flow FM

locationfile = left.pli
forcingfile = simplechannel.bc

[boundary]
quantity = waterlevelbnd
locationfile = right.pli
forcingfile = simplechannel.bc

The final step is to let the model know that the external forcings file simplechannel.ext
is the one that should be used. This is to be achieved in the MDU-file:

T
[external forcing]
ExtForceFile =
AF ExtForceFileNew = simplechannel.ext

Notice that the name is specified at the keyword ExtForceFileNew. The other keyword,
ExtForceFile, should be kept empty, unless deprecated .tim-files and/or .cmp-files are
used to prescribe the physical information for the boundaries.

11.1.1.5 Miscellaneous
In the previous sections, the most essential information on the application of boundary condi-
tions is described. Some remaining aspects are discussed in this section.
DR

Artificial boundary layers

In general, the velocity at the boundary is prescribed as having only a component normal
to the boundary (cstbnd = 0). This could lead to an artificial boundary layer along the
boundary at offshore boundaries. To resolve this behaviour, the advection terms containing
gradients perpendicular to the boundary can be switched off, by setting the keyword cstbnd
= 1 in the [numerics] block in the MDU-file. By default this keyword cstbnd = 0.

Smoothing parameter boundary conditions

The solution of the shallow water equations is uniquely determined by a set of initial and
boundary conditions. The boundary conditions represent the external forcing and determine
the steady state solution. The deviation between the initial condition and the steady state
solution generates a transient (mass spring system analogy).

In D-Flow FM, the initial conditions for the water level and velocities are obtained from:
⋄ The results of a previous run (warm start).
⋄ User-prescribed (space varying or uniform) input fields (cold start).

The initial values are usually inconsistent with the boundary conditions at the start time of the
simulation. This will generate a transient solution consisting of waves with eigen frequencies
of the model domain. These waves may be reflected at the boundaries and generate a stand-
ing wave system. The waves should be dissipated completely by bottom friction and viscosity
terms or leave the domain through the open boundaries. The damping of the transient solution
determines the spin-up time of the numerical model.

To reduce the amplitude of the transient wave and the spin-up time of a model, D-Flow FM has
an option to switch on the boundary forcing gradually by use of a smoothing period (parameter

Deltares 167 of 562

 Boundary conditions in D-Flow FM

Tsmo ). This can by specifying the total number of seconds required for the transition using the
keyword Tlfsmo in the [numerics] block in the MDU-file. With Fi (t) the initial value at
the boundary, Fb (t) the boundary condition signal and Fbsmo (t) the boundary condition after
smoothing, the boundary forcing is given by:

Fbsmo (t) = αFi (t) + (1 − α)Fb (t), (11.3)

where t is the number of seconds since the reference date RefDate and
Tsmo + Tstart,smo − t
α= (11.4)
Tsmo

T
if Tstart,smo < t < Tsmo + Tstart,smo . In case t ≥ Tsmo + Tstart,smo , then the smoothing
parameter is set to zero: α = 0. The behaviour is illustrated in Figure 11.2. The situation
t < Tstart,smo is not possible.
AF
Tsmo
Fb
Fbsmo
DR

Fi
Tstart,smo
Tstart

RefDate t

Figure 11.2: Transitioning between initial conditions Fi and boundary forcing Fb depend-
ing on the smoothing time Tsmo and smoothing start time Tstart,smo for a
case in which the start of start time TStart falls within the smoothing pe-
riod.

Tstart,smo denotes the smoothing start time (not to be confused with the start time TStart)
with respect to the reference time. This is defined using the keyword TStartTlfsmo. By
default it is set to the start time of the simulation (i.e., smoothing is applied since the begin-
ning), and it should be set to the start time of the original simulation when restarting (keyword
TStart).

Smoothing is possible both for a warm and a cold start. If the initial conditions are consistent
with the boundary conditions at the start time of the simulation then the smoothing time should
be set to zero. When restarting a simulation (warm start), the smoothing time should be
reduced by the difference between the original smoothing time (i.e., in the cold start) and the
restart time, and it should be set to zero if the restart time is larger than the original smoothing
time.

Remark:

Deltares 168 of 562

 Boundary conditions in D-Flow FM

⋄ The introduction of the TStartTlfsmo has changed the behaviour of Tlfsmo in

combination with a restart file as of Delft3D Flexible Mesh Suite 2024.03. Previously,
when using a restart file, the simulation was assumed to be correctly adjusted to the
initial conditions, and therefore Tlfsmo was automatically set to zero. This is no longer
the case. To reproduce old model results when using a restart file, manually set
Tlfsmo to zero in the .mdu file.

Secondary boundary conditions

In section 11.1.1.1, several types of boundary conditions are discussed. In addition, two

T
types of boundary conditions can be applied on top of the canonical types: normal veloc-
ities and tangential velocities. The associated keyword are normalvelocitybnd and
tangentialvelocitybnd, respectively.
AF
Bed level at open boundaries
For some evaluations, the solver requires the bed level at the open boundary. This value
depends on the bed level in the ghost cell outside the model domain. By default, the bed level
in the ghost cell is mirrored from the internal grid cell next to the boundary, which means that
a zero bed slope is assumed. While this is perfectly acceptable for most real-life applications,
it hinders obtaining perfect normal-flow solutions in idealized models when using DpuOpt
= 2, i.e. the mean bed level imposed at the cell interfaces. For these specific cases, an
option has been implemented to extrapolate the bed level outside the domain. When setting
[geometry] keyword ExtrBl = 1, the bed levels at the ghost cells are extrapolated in
such a way that the flow depth at velocity points can be exact in idealized cases.1 This option
is only available when the bed level is specified at the cell centres (BedlevType = 1).
DR

Furthermore, for obtaining perfect normal flow, the downstream water level needs to be spec-
ified at the ghost cell (izbndpos = 0) and the conveyance needs to be computed based on
a uniform bed level based on the surrounding net nodes (Conveyance2D = -1). Note that
the boundary condition must be manually shifted by s∆x, being s the slope, from the exact
value expected at the domain boundary (cell edge).2

Suppose a case in which a specific discharge q of 1 m2 /s is fed into a rectangular channel

of constant width and constant slope s equal to −7.1356 × 10−4 . Wall friction is neglected.
Friction is using Chézy with parameter C equal 3.743 57 × 101 m1/2 /s, such that the normal
flow depth, given by h = (q 2 /C 2 /s)1/3 , becomes 1 m. A grid with streamwise space step
∆x of 20 m is employed. The bed level at the dowstream end of the domain (the cell edge)
is −1 mAD, such that the water level boundary condition for obtaining perfect normal flow is
0 mAD at the cell edge. This condition is obtained by setting the water level at the ghost cell
equal to s∆x = −0.014 27 (izbndpos = 0).

Figure 11.3 shows the cell-centre velocity of the idealized case described above when using
and not using the bed level extrapolation. Figure 11.4 shows the flow depth at velocity points
and Figure 11.5 the flow depth at cell centres. When extrapolating the bed level, the flow
depth at velocity points and the velocity at cell centres (and velocity points) are equal to the
desired normal-flow case values. However, the flow depth at cell centres is smaller. This is
because the D-Flow FM numerical scheme uses at the cell interfaces the upwind water level.
1
The bed levels are extrapolated in line with the internal slope at water level boundaries, but with the reverse
slope at velocity/discharge boundaries since the model uses the water level of the internal grid cell at the open
boundary in the latter case.
2
One would expect that the boundary condition should only be reduced by half that value, but the water level
at the cell interfaces is determined by the value of the upwind cell centre. The water level to be specified at the
ghost cell should be consistent with that trend.

Deltares 169 of 562

 Boundary conditions in D-Flow FM

velocity magnitude [m/s]

1.004

1.002 ExtrBl = 1
ExtrBl = 0
1

500 1000 1500

distance along section [m]

T
Figure 11.3: Cell-centre velocity magnitude along the streamwise direction of an idealized
normal-flow case. ExtrBl = 1 extrapolates the bed levels at the boundaries
and perfect normal flow is obtained.
AF
depth at velocity point [m]

1.001
ExtrBl = 1
1 ExtrBl = 0

0.999
500 1000 1500
DR

distance along section [m]

Figure 11.4: Flow depth at velocity points along the streamwise direction of an idealized
normal-flow case. ExtrBl = 1 extrapolates the bed levels at the boundaries
and perfect normal flow is obtained.

If the water depth at the interface matches the normal-flow water depth, then the water depth
at the upstream cell centre will be smaller since the same water level is combined with a
higher cell-centre bed level.

11.1.2 Vertical boundary conditions

The vertical boundary conditions close the system of shallow water equations at the bed level
and the free surface level. Without precipitation, evaporation or ground water flow, there is by
definition no flow through the bottom or top surface of the water column. The vertical boundary
conditions for the continuity equation 3.3 are most easily expressed when the σ co-ordinate is
used for the vertical direction. In that case the free surface (σ = 1, or z = ζ ) and the bottom
(σ = 0, or z = zb ) are σ co-ordinate surfaces. ω is the vertical velocity relative to the σ -
plane. The impermeability of the surface and the bottom is taken into account by prescribing
the following kinematic conditions:

ω|σ=1 = 0 and ω|σ=0 = 0 (11.5)

Deltares 170 of 562

 Boundary conditions in D-Flow FM

T
AF
0.994
depth [m]

ExtrBl = 1
0.993 ExtrBl = 0
DR

0.992

500 1000 1500

distance along section [m]

Figure 11.5: Cell-centre flow depth along the streamwise direction of an idealized normal-
flow case. ExtrBl = 1 extrapolates the bed levels at the boundaries and
perfect normal flow is obtained.

Deltares 171 of 562

12 Hydraulic structures
Obstacles in the flow may generate sudden transitions from flow contraction to flow expansion.
The grid resolution is often low compared to the gradients of the water level, the velocity
and the bathymetry. The hydrostatic pressure assumption may locally be invalid. Examples
of these obstacles in civil engineering are: gates, barriers, dams, groynes and weirs. The
obstacles generate energy losses and may change the direction of the flow.

The forces due to obstacles in the flow which are not resolved (sub-grid) on the horizontal grid,
should be parameterised. The obstacles are denoted in D-Flow FM as hydraulic structures.

T
In the numerical model the hydraulic structures should be located at velocity points of the
grid. The direction of the forces should be specified at input. To model the force on the flow
generated by a hydraulic structure, a quadratic energy or linear loss term is added to the
momentum equation.
AF
Note: Structure definitions can be made in Delta Shell, and will then be saved into a struc-
tures <∗.ini>-file (section C.12).

The user can insert the hydraulic structures by the means of polygons on the grid. By select-
ing the required structure and drawing a polygon on the computational grid, the location of
structure can be defined (see Figure 12.1). The supported structures in D-Flow FM are

⋄ Fixed Weirs
⋄ Dambreaks
⋄ Gates
⋄ (Adjustable) general structures, weirs, gates, orifices, and universal weirs,
DR

⋄ Culverts
⋄ Long culverts
⋄ Bridges
⋄ Pumps
⋄ Compound structures
⋄ Long culverts
⋄ Thin dams

In practice, the word ’barrier’ is often used for structures. However, in D-Flow FM such struc-
tures are modelled as a gate or a weir in combination with a so-called Control Group (D-Real
Time Control model).

Figure 12.1: Selection of structures (and other items) in the toolbar.

Deltares 172 of 562

 Hydraulic structures

12.1 Fixed weirs

In D-Flow FM, a fixed weir is a fixed non-movable construction generating energy losses due
to constriction of the flow. They are commonly used to model sudden changes in depth (roads,
summer dikes) and groynes in numerical simulations of rivers. Such structures are applied
to keep the river in its bed for navigation purposes. Others are built, for instance, to protect
an area behind a tidal weir from salt intrusion. Upstream of a weir the flow is accelerated
due to contraction and downstream the flow is decelerated due to expansion. The expansion
introduces an important energy loss due to turbulence. The energy loss is dependent on the
shape of the weir and its crest level.

T
Fixed weirs are located in D-Flow FM on the velocity points of the computational grids. For a
description of the input of fixed weirs, we refer you to section 7.4.2.5 and C.8.

In D-Flow FM, three different approaches are applied to simulate the energy losses by fixed
AF weirs. First of all, a numerical approach has been implemented. Then, a special discretization
of the advective terms around the fixed weir is applied. For a detailed description we refer to
Deltares (2025a, section 6.7.1 – 6.7.4).

Next to the numerical approach, there is an empirical approach. Based on measurements in

flume laboratories empirical formulae can be derived in order to match the measurements as
accurately as possible. In this empirical approach, the energy loss due to a weir is described
by the loss of energy height ([m]). The energy loss in the direction perpendicular to the weir is
denoted as ∆E . This energy loss is added as an opposing force in the momentum equation
by adding a term −g∆E/∆x to the right hand side of the momentum equation, resulting in a
jump in the water levels by ∆E at the location of the weir. For the computation fo the energy
DR

loss ∆E two options are availabe in D-Flow FM, namely the so-called ’Tabellenboek’ and
’Villemonte’ approaches. The two corresponding empirical formulas have been taken from
the Simona software suite. For a detailed description of both formulas we refer to Deltares
(2025a, section 6.7.5 – 6.7.6). In this empirical approach the discretization of the advective
terms does not change, unlike the numerical approach in D-Flow FM for modelling fixed weirs.

The third approach is only available for fixed weirs that are located on 1D2D connections. For
this approach a weir formula is used to compute the flow over the fixed weir. For a detailed
description of this approach see Deltares (2025a, section 6.9.3). This approach can be turned
on by setting FixedWeirScheme1d2d=1 under the paragraph [numerics] in the MDU-
file. Note: The non-1D2D fixed weirs will not be affected by this keyword.

12.2 Dam break

The dam break is a structure that models a growing breach after a dam failure or levee breach.
A dam break is not really a hydraulic structure, but since it shares several properties with other
structures (in terms of input and output), it is included here. The calculation of flow through a
breach is based on a fixed weir (section 12.1), which models energy losses across the crest.
Therefore, one important requirement of a dam break is that, a fixed weir polyline must be
present on the same location as the dam break polyline. The dam break structure lowers the
crest level and widens the breach width over time.

The input file format for a dam break is described in section C.12.11 and the output options in
section F.3.1.8.8.

In this section, firstly, the geometrical grid snapping of dam break polylines to 2D grid lines is
discussed. Then the computation of breach growth of a dam break is discussed. This includes
two empirical formulas for computing breach growth: Verheij–van der Knaap (2002) and van

Deltares 173 of 562

 Hydraulic structures

der Knaap(2000).

12.2.1 Grid snapping of a dam break

The potential location of a dambreak is defined by an input dam break polyline. This should
coincide with (part of) a fixed weir polyline. When initializing a model, the geometrical snap-
ping of these polylines to the grid cell edges is identical for both. The rule of this snapping is,
if the polyline intersects with a flow link, then it is snapped to the cell edge that intersects with
this flow link.

T
The user defines the start location of the dam breach by means of providing the coordinates
(startLocationX, startLocationY). The actual starting point of the dam breach is
determined by the following steps:
1 The nearest point on the dam break polyline to the start location is determined, by pro-
AF jecting the start location onto the polyline.
2 For all flow links in the dam break, the intersection of these flow links with the dambreak
polyline are computed.
3 The flow link with its intersection that is closest to the the projected start location will be
used as the actual midpoint location of the dam breach.

More details are available in the section about fixed weir snapping in (Deltares, 2025a, sec-
tion 6.7.7). Note that a start location for a breach that is placed in the middle of a dam
break, may not be located in the middle after snapping. This is most obvious when a dam
break snaps to an even number of flow links/grid edges equal lengths. This is of particu-
lar importance when the breach width grows to about the full width of the dam break. See
DR

section 12.2.2.4 for more details.

Fixed weirs and dambreaks on a 2D grid

To correctly model the crest width of a fixed weir (and the breach width), the flow link widths
at the grid-snapped polylines are adjusted. Assume that the fixed weir polyline intersects with
a flow link j ′ , associated with cell edge j . Then flow link width wuj is computed as:

wuj = cos(α) ||Edge||j , (12.1)

where
wuj is the flow link width,
||Edge||j is the original length of cell edge j (i.e., the original width of flow link j ′ ), and
α is the angle between the fixed weir polyline and cell edge j .

In other words, wuj is the projection of the original width of edge j onto the fixed weir polyline.
As a result, when summing wuj for all affected flow links j ′ , the total width is similar to the
length of the polyline.

12.2.2 Computation of breach growth

Two formulas are available to compute the breach growth of a dam break in D-Flow FM:
Verheij–Van der Knaap(2002) and Van der Knaap (2000). These are discussed first. Alter-
natively, breach width and depth may be provided by the user as a time series. Finally, the
details of a breach width spanning multiple flow links is discussed.

Both breach growth formulas regard the process of breach growth as two phases:

Deltares 174 of 562

 Hydraulic structures

⋄ Phase 1: during which the breach level, for a constant initial breach width, is lowering
from its initial crest level zcrest (or dike level) to its minimal crest level zmin . In other words,
this phase is a "lowering" phase. The breach level decreases while the breach width stays
unchanged.
⋄ Phase 2: during which the breach only grows in width under a certain condition depending
on the formula in use. The Verheij–Van der Knaap (2002) formula increases the breach
width based on the water level jump, as long as the flow velocity through the breach is
larger than the critical flow velocity for eroding sediment/soil particles uc . The Van der
Knaap (2000) formula computes the breach width as a function of time and limits it by a
maximal breach width. In other words, this phase is a "widening" phase. The breach level

T
stays at the minimal level and the breach width increases.

12.2.2.1 The Verheij–Van der Knaap (2002) formula

One can choose to use the Verheij–Van der Knaap (2002) formula by setting the input param-
AF eter algorithm=2 in Table C.23. The formula is as follows:

Phase 1:

For Tstart ≤ t ≤ Tstart + tPhase 1

B(t) = B0 , (12.2)
 
t − Tstart
z(t) = zcrest − (zcrest − zmin ). (12.3)
tPhase 1
Phase 2:
DR

For t > Tstart + tPhase 1 (hence B(t) ≥ B0 ):

z(t) = zmin , (12.4)

 
∆t ∂B
B(ti+1 ) = B(ti ) + , (12.5)
3600 ∂t ti+1

where

f1 f2 (g(hup −max(hdown ,zmin )))3/2 1
|u| > uc
 
∂B 
ln(10) u2c f g (ti+1 −t1 ) if
1+ 2 3600 uc . (12.6)
∂t ti+1
0 if |u| ≤ uc

The notations in the above formula are:

f1 (input parameter) Factor 1: constant factor [−],
f2 (input parameter) Factor 2: constant factor [−],
B(t) Width of the dam breach at time t [m],
B
 0  (input parameter) Initial width of the dam breach [m],
∂B
Rate of breach width growth in time-step ∆t from ti to ti+1 [m/s],
∂t ti +1
g Acceleration due to gravity [m/s2 ],
hup Upstream water level at time t [m AD],
hdown Downstream water level at time t [m AD],
t Current model time [s],
tPhase 1 (input parameter) Duration of phase 1, the time period over which the breach
for a constant initial width (B0 ) is lowered from its initial crest level zcrest (or dike
level) to its minimal crest level zmin [s],

Deltares 175 of 562

 Hydraulic structures

t1 = Tstart + tPhase 1 The time [s] when the maximum breach-depth (zmin ) is reached, i.e.
when the Phase 1 finishes,
Tstart (input parameter) Model time at which the development of the initial breach
starts [s],
u Average flow velocity in the breach [m/s],
uc (input parameter) Constant critical flow velocity for eroding sediment/soil parti-
cles.
z(t) Crest level of the dam breach at time t [m AD],
zcrest (input parameter) Initial breach level at t = Tstart [m AD],
zmin (input parameter) Minimal breach level at t = t1 [m AD],

T
∆t Computational time step [s], equal to ti+1 − ti .

Settings of the input parameters can be found in section C.12.11.

Upstream and downstream water levels (hup and hdown )

AF
By default the upstream and downstream water levels are computed by averaging the water-
levels upstream and downstream of the dambreak. Only grid cells that are connected to a flow
link that is (partly) opened by the dambreak are included in the averaging. For the averaging
of upstream and downstream water level the original flow width of the open flow links is used
as a weight factor.

Another possibility is to define custom up and downstream water level locations. In Sec-
tion C.12.11 the input settings for this option can be found.
DR

Recommended values of input parameters in the Verheij–Van der Knaap (2002)

formula
To use proper values, a list of recommended values as well as the range of values is given in
Table 12.1.

Table 12.1: Recommended values of input parameters in the Verheij–Van der Knaap
(2002) formula.

Parameter recommended value Range

f1 1.3 0.5 - 5
f2 0.04 0.01 - 1
B0 10 1 - 100 m
tPhase 1 0.1 hours 0.1 - 12 hours
uc 0.2 m/s 0.1 - 10 m/s
zcrest - -
zmin - -

Deltares 176 of 562

 Hydraulic structures

Characterising soil strength

As a recommendation, the parameter uc , applied in the Verheij–Van der Knaap (2002) formula
may be derived from Table 12.2, where τc is the critical shear stress.

Table 12.2: Recommended values for uc and τc .

Soil type Bodemtype (Dutch) uc τc

[m/s] [Pa]
grass, good gras, goed 7 185

T
grass, moderate gras, matig 5 92.5
grass, bad gras, slecht 4 62
clay, very good klei, zeer goed (compact; tongedraineerd 1.0 4
(compacted) = 80 – 100 kPa)
AF clay, good
(firm)
clay, moderate
klei met 60 % zand,
(stevig; tongedraineerd = 40 – 80 kPa)
goede klei met weinig structuur
0.8

0.7
2.5

2
(little structure)
clay moderate goede klei, sterk 0.6 1.5
(considerable structured)
clay, bad slechte klei 0.4 0.65
(weak) (slap; tongedraineerd = 20 – 40 kPa)
sand with 17 % silt zand met 17 % silt 0.225 0.20
DR

sand with 10 % silt zand met 10 % silt 0.20 0.15

sand with 0 % silt zand met 0 % silt 0.16 0.10

Another way to compute uc is using the critical shear stress τc . For example, if τc is known,
then uc can be calculated by
√
uc = 0.5 τc , (12.7)

or

uc = uc,sand (1 + 0.01αPclay ) + β(0.65 − v), (12.8)

where using the defaults, factor α = 15, factor β = 1, critical flow rate for sand uc,sand = 0.2
m/s, Pclay is percentage of clay, and the voids ratio v can be computed by

v = n/(1 − n), (12.9)

where n is the soils pore fraction (default n = 0.4).

For more details of formula Verheij–Van der Knaap (2002) we refer to Verheij (2002).

12.2.2.2 The Van der Knaap (2000) formula

One can choose to use the Van der Knaap (2000) formula by setting the input parameter
algorithm=1 in Table C.23. The formula is as follows:

Phase 1:

Deltares 177 of 562

 Hydraulic structures

For Tstart ≤ t ≤ Tstart + tPhase 1

B(t) = B0 , (12.10)
 
t − Tstart
z(t) = zcrest − (zcrest − zmin ). (12.11)
tPhase 1
Phase 2:

For t > Tstart + tPhase 1 (hence B(t) ≥ B0 ):

T
z(t) = zmin , (12.12)
 
t
B(t) = min c1 log10 ( ), Bmax . (12.13)
AF c2

In Equation (12.13), the coefficients c1 , c2 and allowed maximal breach width Bmax depend on
the material of the dam. Two types of materials are possible: clay and sand. (Currently only
clay is supported in D-Flow FM.) The values of these coefficients are shown in Table 12.3.

Table 12.3: Values of coefficients c1 , c2 and Bmax of the Van der Knaap (2000) formula
for different material types.

Material type c1 c2 Bmax

clay 20 288 75 m
sand 67 522 200 m
DR

Other notations in the above formula are:

B(t) Width of the dam breach at time t [m],
B0 (input parameter) Initial width of the dam breach [m],
t Current model time [s],
tPhase 1 (input parameter) Duration of phase 1, the time period over which the breach
for a constant initial width (B0 ) is lowered from its initial crest level zcrest (or dike
level) to its minimal crest level zmin [s],
Tstart (input parameter) Model time at which the development of the initial breach
starts [s],
z(t) Crest level of the dam breach at time t [m AD],
zcrest (input parameter) Initial breach level at t = Tstart [m AD],
zmin (input parameter) Minimal breach level at t = t1 [m AD],

Settings of the input parameters can be found in section C.12.11.

For more details about formula Van der Knaap (2000) we refer to Van der Knaap (2000).

12.2.2.3 Breach crest level and width time series

One can choose to explicitly prescribe the breach’s crest level and width as time series by set-
ting the input parameter algorithm=3 in Table C.23. The provided time series must be in a
3-column <*.tim> file (in minutes), specified by parameter dambreakLevelsAndWidths.
The times in the file are relative to Tstart (t0, in seconds).

Deltares 178 of 562

 Hydraulic structures

12.2.2.4 Method when breach grows wider than one flow link
The breach starts at only one flow link, which is defined by setting startLocationX and
startLocationY in the input, see section C.12.11. The breach widths during the sim-
ulation are computed by either the formulas for breach growth or by a time series. At a
certain time, if the breach width is wider than the starting flow link, D-Flow FM must deter-
mine the affected links so that the width grows, from the starting flow link, to gradually include
more edges. How the breach extends beyond the starting flow link is determined by the
breachGrowth keyword in the <mdu-file>; three options have been implemented.
⋄ symmetric In this case the breach grows symmetrically on both left and right sides of

T
the breach. This is the original implementation. This approach triggers a warning when
the breach reaches the end of the snapped dam break on one of the sides.
⋄ symmetric-asymmetric In this case the breach is assumed to grow symmetrically
on both left and right sides of the breach until it reaches the end of the dam break on one
of the sides; thereafter it only growth on the other side. This is the current default. This
AF approach triggers a warning only when the breach width is larger than the full length of
the snapped dam break.
⋄ proportional In this case the breach is assumed to grow proportionally to the avail-
able width on the two sides of the breach. This approach triggers a warning only when the
breach width is larger than the full length of the snapped dam break.

Given the breach width on one of the sides, for instance a width on the left side wleft , links
on the left side are opened one by one in sequence gradually moving further away from the
starting flow link:
⋄ Situation 1: If wleft is smaller than the width of the considered flow link, then this is end of
DR

the searching.
⋄ Situation 2: If wleft is larger or equal to the width of the considered flow, the value of wleft
is decreased by this flow link width and the process continues with the next flow link that
is on the left side of this link. This is repeated until Situation 1 is achieved, or the end of
the dam break is reached.

In both two situations, the width and bed level of the considered link is affected. The bed
level of this link is adjusted to the maximal value of its original bed level and the crest level of
the dam break. The width of this link is adjusted to the effective dam breach width, i.e. the
minimum of the remaining breach width wleft and the width of the flow link.

12.3 General structure

The General structure combines weir and gate flow into one structure. Additionally, the Gen-
eral structure gives the highest degree of freedom in defining the the geometry of the hydraulic
structure and coefficients affecting the flow. The geometrical shape is given in Figure 12.2 and
Figure 12.3. The discharge through a General structure is computed based on upstream and
downstream energy levels. The input file format for a general structure is described in sec-
tion C.12.10.

Deltares 179 of 562

 Hydraulic structures

Gate upper edge level

Gate height

Gate lower edge level

ζup

T
Q, u, AF Gate opening height
ζdown

zs
AF zu1
Chainage
zu2

Length
zd1
zd2
Datum/reference level

Figure 12.2: General structure, side view

DR

wu1 wu2 ws wd1 wd2

Crest length

Chainage

Figure 12.3: General structure, top view

The gate of the General structure can be configured as two doors with an opening in between
as shown in Figure 12.4. When the modelled gate is a single door spanning the full width, the
Gate Opening Width should be set to zero.

Deltares 180 of 562

 Hydraulic structures

Flow over gate Gate upper edge level Flow over gate

Gate height Gate opening width

Gate lower edge level

T
Flow under gate Flow through gate opening width Flow under gate

Crest width
AF Crest level

Datum/reference level

Figure 12.4: General structure, front view

Figure 12.4 also shows the three different geometrical parts where the General structure can
have flow: under gate flow, over gate flow and between gate flow. The total discharge through
the structure is calculated by adding up the discharge through the separate parts. For each
DR

part of the structure opening the downstream waterlevel is calculated and subsequently the
flow type (gate or weir, free or submerged) is determined.

Remark:
⋄ Please keep in mind that in the following part of this section the description for the Gen-
eral structure applies to the three different openings (with each its own flow conditions).

During the simulation a number of checks and possibly corrections on some dimensions of
the general structure are performed.
⋄ If the crestLevel is below the bed level of the surrounding water level points in the
channel, the crestLevel (zs ) is raised to the highest bed level of these two points1 .
⋄ If zu1 and/or zu2 are below the bed level of the upstream water level point in the channel,
zu1 and/or zu2 are raised to the bed level of the upstream water level point in the channel.
⋄ If zd1 and/or zd2 are below the bed level of the downstream water level point in the chan-
nel, zd1 and/or zd2 are raised to the bed level of the downstream water level point in the
channel.
⋄ All widths (ws , wu1 , wu2 , wd1 , wd2 ) are maximized with the corresponding flow width.
⋄ If the gateLowerEdgeLevel is lower than the crestLevel, the gateLowerEdgeLevel
is set to the crestLevel.
⋄ If the gateHeight is less than or equal to 0 an error message is produced.
⋄ If the gateOpeningWidth is less than 0, the gateOpeningWidth is set to 0.
Else if the gateOpeningWidth is larger than the crestWidth then the gateOpeningWidth
is set to the crestWidth.
1
The bed level check is actually based on the face-based bed levels of the velocity point. In typical applications,
this is equal to the maximum bed level of the two surrounding water level points. More information is available in
(Deltares, 2025a, Equation (6.10)).

Deltares 181 of 562

 Hydraulic structures

Flow across the General structure can be of the following types:

⋄ free gate flow (i.e. supercritical gate flow),
⋄ submerged gate flow (i.e. subcritical gate flow),
⋄ free weir flow (i.e. supercritical weir flow), and
⋄ submerged weir flow (i.e. subcritical weir flow).

The choice depends on the dimensions of the structure and the flow conditions. Whether
or not the gate is in the flow or above the flow yields either gate or weir flow. Furthermore,
the flow can be either subcritical (submerged) or supercritical (free). Both for incoming flow

T
("Flow") and for outgoing flow ("Reverse") contraction coefficients can be specified. These
coefficients can be seen as tuning parameters for the user.

12.3.1 Notation
AF The used variables in this subsection are described in this paragraph.

The five geometric parameters as shown in Figure 12.2:

zs Crest level,
zu1 Level upstream 1,
zu2 Level upstream 2,
zd1 Level downstream 1, and
zd2 Level downstream 2

Similarly for the five values for the width of the General structure, see Figure 12.3:
DR

ws Width at crest level,

wu1 Width upstream 1,
wu2 Width upstream 2,
wd1 Width downstream 1, and
wd2 Width downstream 2

Other variables used in the equations of this subsection:

C Chézy value, representing the roughness at the downstream side of the General
structure
cgf Correction coefficient for free gate flow
cgd Correction coefficient for submerged gate flow
cwf Correction coefficient for free weir flow
cwd Correction coefficient for submerged weir flow
E1 Energy height upstream (= ζup + u2 /(2g))
g Acceleration due to gravity
2
Hs1 Energy height with respect to the crest level (= E1 − zs = ζup + u2g − zs )
hg Opening height of the gate (= gateLowerEdgeLevel − zs )
L Length of the expansion zone at the downstream side of the General structure
h2 Water depth downstream of the structure with respect to the crest level (=
ζdown − zd2 ), see remark below.
∆S1 = zs − zd1
∆S2 = zd1 − zd2
λ Extra resistance parameter
ρ∗ = ρ2 /ρ1
ρ1 Density of the water at the upstream side of the General structure [kg/m3 ]
ρ2 Density of the water at the downstream side of the General structure [kg/m3 ]
µgf Contraction coefficient for free gate flow

Deltares 182 of 562

 Hydraulic structures

µgd Contraction coefficient for submerged gate flow (µgd = µgf )

Remarks:
  23
⋄ Downstream water depth h2 is limited to a minimal value of 0.9 · 32 · Hs1 · wwd2s .
⋄ The effect of this limiter might result in an incorrect flow state. In case the downstream
level zd2 is similar to the crest level zs and the downstream width wd2 is similar to the
crest width ws , the general structure might not reach the free flow state.
⋄ The energy heights E1 , Hs1 can be set to ordinary water levels in case the flag UseVelocityHeight
is set to False. For more information, see section 12.3.4.

T
12.3.2 Geometry
The crest level, gate lower edge level and gate door opening width can also be given as time
series.
AF A (2D) hydraulic structure is given as a single geometrical object by the user, but it may cross
multiple 2D grid cells (or: flow links). In case a General structure is positioned on a 1D
branch, a structure crosses only 1 link. Each flow link under the influence of this structure (i.e.
structure link) is treated as a General structure with the correct geometrical parameters.

Remark:
⋄ In case a General structure crosses multiple 2d flow links, wu1 , wu2 , wd1 and wd2 are
all set per individual link to the crest width per link (ws (L)).
DR

Crest width
The crest width of an individual flow link, under the influence of this structure, cannot exceed
the width of this flow link. As a result, when the crest width exceeds the sum of the widths of
the structure links, the crest width is reduced to the sum of the widths of the flow links. When
the crest width is omitted in the input the structure width will be set to the sum of the widths of
the structure links.

Remark:
⋄ Keep in mind that in case a polyline has e.g.√an angle of 45 degrees with the grid, the
sum of the flow widths might be a factor of 2 larger than the polyline. Therefore it is
recommended to align the grid with the structure.

In case the crest width is smaller than the sum of the widths of the structure links, the following
algorithm is applied:
⋄ Use the next definitions
wu (L) is the flow width of a structure link
N is the total number of structure links in a structure
ws is the total crest width
ws (L) is the crest width of a structure link
PN
wclosed = L=1 wu (L) − ws

Deltares 183 of 562

 Hydraulic structures

⋄ Determine smallest p and largest q where

p
!
X
wu (L) − 0.5 · wclosed > 0 (12.14)
L=1
q
!
X
wu (L) − 0.5 · wclosed < 0 (12.15)
L=1

⋄ The crest widths of the structure links 1 until q will be set to 0 (i.e. closed)
⋄ The crest width of structure link p = q − 1 will become:

T
p
!
X
ws (p) = wu (L) − 0.5 · wclosed (12.16)
L=1

⋄ A similar approach is applied to the right side of the structure.

AF
⋄ A a result the opening of the structure will be right in the middle of the set of structure
links.

Example for the left part of the structure:

Assume the total crest width is 550 [m] (ws ), the total flow width is 1000 [m] and the number
of structure links is set to 5 (N ). So each structure link has a width of 200 is [m] (wu (L)),
PN
the total flow width is indeed 1000 [m] ( L=1 wu (L)) and thus wclosed is 450 [m]. According
Equation (12.14) we get p = 2, and according Equation (12.15) we get q = 1. The partial
open/closed structure link ws (p) has a crest width of 175 [m], according Equation (12.16)
DR

(175 = 400 − 225). The total crest width is: ws (2) + ws (3) + ws (4) = 175 + 200 + 175 =
550 [m]. Taken into account the symmetry between left and right side of the structure.

Gate opening
The GateOpeningWidth is a compulsory parameter for General structures. A single gate
door with no horizontal movement should use GateOpeningWidth=0. A structure that has
one or two gate doors that do have horizontal opening and closing movement should specify
the width of the horizontal opening beteen the doors.

Depending on the gate door positions, some structure links may have only flow across the
weir crest in the opening, whereas others may have gate flow, or a combination of both. A
similar algorithm for applying the gate door to the individual flow is performed as described for
the crest width. There is an exception, because the door might not close symmetrical. The
parameter GateOpeningHorizontalDirection defines the way a gate door is divided
over the structure links. Possible values are symmetric, fromLeft, fromRight.

At both ends of the gate opening structure links may be partially opened in such a way that
the gateOpeningWidth exactly matches the sum of the width of the open flow links.

Extra resistance
The extra resistance parameter λ relates to the friction force in the impulse balance, that in
case of submerged gate flow or submerged weir flow is solved for the water movement at the
downstream side of the General structure. The extra resistance parameter λ is given by the
expression:

gL
λ= (12.17)
C2

Deltares 184 of 562

 Hydraulic structures

For an explanation of the variables see section 12.3.1.

Either the extra resistance parameter, λ, can be specified, or the length, L, can be specified
by the user. In case length is used, the Chézy value of the flow link is used for calculating λ.

12.3.3 Computation of the downstream water level

In case of submerged gate flow or submerged weir flow the water level at the sill or down-
stream of the gate is required. This level is computed by application of the impulse balance.

T
Remark:
⋄ The equations in this paragraph apply to flow in positive direction for flow in negative
direction replace the next variables in the equations:
⋄ zd1 into zu2
⋄ zd2 into zu1
AF ⋄
⋄
wd1 into wu2
wd2 into wu1

Submerged gate-flow

Gate height
DR

ζup
ζdown
Q, u, AF Gate opening height

zs
zu2 zd1
zu1 zd2
Chainage Length Datum/reference level

Figure 12.5: Submerged gate flow

The water depth on the crest hs can be described by a second order algebraic equation:

Ag h2s + Bg hs + Cg = 0 (12.18)

Deltares 185 of 562

 Hydraulic structures

with:
w wd2  w wd2 
d1 d1
Ag = (1 + ρ∗ ) + + (1 − ρ∗ ) + (12.19)
 3 6 w 4
wd2  12
wd1
d1
Bg = (1 + ρ∗ ) (∆S1 + ∆S2 − h2 ) + + (2∆S1 + h2 ) +
3 6 6
wd2 
(∆S1 + 2h2 ) +
 6 
∗ wd1 wd1 + wd2
+ (1 − ρ ) ∆S1 + (∆S1 + h2 ) +
3 6

T
4ρ∗ c2gd µ2gd h2g ws2 λ
+ (1 + ) − 4cgd µgd hg ws (12.20)
wd2 h2 d2
 wd1 wd2 
Cg = (1 + ρ∗ )(∆S1 + ∆S2 − h2 ) 2∆S1 + h2 ) + (∆S1 + 2h2 ) +
6  6
AF 
+ (1 − ρ∗ ) (∆S1 )2

4ρ∗ c2gd µ2gd h2g ws2 Hs1

wd1
6
+ (∆S1 + h2 )
wd1 + wd2
12
+

λ
− (1 + ) + 4cgd µgd hg ws Hs1 (12.21)
wd2 h2 h2
For an explanation of the variables see section 12.3.1.

Equation (12.18) leads to:

p 2
−Bg + Bg − 4Ag Cg
DR

hs = (12.22)
2Ag

Submerged weir-flow

Q, u, AF
ζup ]
Hs ζdown
hs
Eup
Edown
zs
zu2 zd1
zu1 zd2
Chainage Length Datum/reference level

Figure 12.6: Submerged weir-flow.

The water depth at the sill hs is described by a third order algebraic equation:

Dw h3s + Aw h2s + Bw hs + Cw = 0 (12.23)

Deltares 186 of 562

 Hydraulic structures

with:

4ρ∗ c2wd ws2 λ

Dw = (1 + ) (12.24)
wd2 h2 h2
w wd2   wd1 wd2 
d1
Aw = (1 + ρ∗ ) + + (1 − ρ∗ ) + +
3 6 4 12
4ρ∗ c2wd ws2 Hs1 λ
− (1 + ) − 4cwd ws (12.25)
wd2 h2 h2
 w wd2  wd1
d1
Bw = (1 + ρ∗ ) (∆S1 + ∆S2 − h2 ) + + (2∆S1 + h2 ) +

T
3 6 6
wd2 
(∆S1 + 2h2 ) +
 6 
∗ wd1 wd1 + wd2
+ (1 − ρ ) ∆S1 + (∆S1 + h2 ) + 4cwd ws Hs1 (12.26)
3 6
AF 
wd1

Cw = (1 + ρ∗ )(∆S1 + ∆S2 − h2 ) (2∆S1 + h2 )
wd1
6
+ (∆S1 + 2h2 )
wd1 + wd2

wd2 
6
+

+ (1 − ρ∗ ) (∆S1 )2 + (∆S1 + h2 )2 (12.27)

6 12

A direct method is applied to calculate hs from equation Equation (12.23).

12.3.4 Turning off the computation of the energy levels

DR

The input parameter useVelocityHeight in the <structures.ini> file (section C.12) can
be used to change the default way of solving the flow through the structure. For certain situa-
tions the default setting might lead to incorrect results. The reason is that the general structure
was developed for modelling structures in an open channel (river or rural applications), and
the preceding approximations are based on certain assumptions. When applied to urban ap-
plications, some of these assumptions may not hold. Also important to realize is that the weir
and orifice are based on the same formulations and assumptions.

The default setting, useVelocityHeight=true, is the situation as described in the pre-

vious section on water level computations. The upstream energy level is defined as

E1 = ζup + u2 /(2g) (12.28)

and the downstream water depth (hs ) is determined as described in section 12.3.3.

The alternative setting, useVelocityHeight=false, simplifies the governing equations

for E1 and hs . This can be of use when modelling a sewer system, where an overflow is
also modelled as a general structure. Simple (gated) weir flow depending on simple water
levels is preferred in such a case. The first difference compared to open water channels is
that upstream horizontal velocities in an urban manhole compartment will typically be almost
zero. The upstream energy height then simplifies to the upstream water level:

E1 = ζup . (12.29)

The second difference is that the general structure’s geometry simplifies to a long crest with
zu1 = zu2 = zs = zd1 = zd2 . The downstream water depth can no longer be derived from
the accelaration across this (flat) crest, so it is simply based on downstream water level:

hs = ζdown − zs . (12.30)

Deltares 187 of 562

 Hydraulic structures

12.3.5 Discharge equations

The following discharge equations are applied during the computations.
⋄ Free gate flow:
q
us = µgf cgf 2g(E1 − (zs + µgf hg )) (12.31)
Af = ws hg (12.32)
q
Q = us Af = µgf cgf ws hg 2g(E1 − (zs + µgf hg )) (12.33)

T
⋄ submerged gate flow:
p
us = µgd cgd 2g(E1 − (zs + hs )) (12.34)
Af = ws hg (12.35)
AF p
Q = us Af = µgd cgd ws hg 2g(E1 − (zs + hs )) (12.36)
(12.37)

⋄ Free weir flow:

r
2
us = cwf g(E1 − zs ) (12.38)
3
2
Af = ws (E1 − zs ) (12.39)
3 r
DR

2 2
Q = us Af = cwf ws g(E1 − zs )3/2 (12.40)
3 3
⋄ submerged weir flow:
p
us = cwd 2g(E1 − (zs + hs )) (12.41)
Af = ws hs (12.42)
p
Q = us Af = cwd ws hs 2g(E1 − (zs + hs )) (12.43)

For an explanation of the variables see section 12.3.1.

Remarks:
⋄ The contraction coefficient has a maximum value µ = 1.0. In case the user specifies a
higher value, a warning will be generated.
⋄ For all the coefficients two values must be specified. One for flow in positive direction
and another for flow in negative direction.

Determining the flow type

The flow type is determined by this algorithm:
⋄ Determine hs based on submerged weir flow equations
⋄ Use critical weir flow depth hc = 23 (E1 − zs )
⋄ Test weir flow
If (hs > hc and hg > hs ) then submerged weir flow
⋄ ⋄ ⋄

Else if (hs < hc and hg > hc ) then free weir flow

Else gate flow:

Deltares 188 of 562

 Hydraulic structures

◦ The water depth at the sill hs is recalculated using the submerged gate flow equa-
tions. The critical depth hc is now defined as µgf hg .
▷ If (hs < hc or if hs cannot be solved) then free gate flow
▷ Else submerged gate flow

Remark:
⋄ In case upstream water level is above gate lower edge level, there can still be sub-
merged weir flow if ζs > hc and hg > ζs or free weir flow if ζs < hc and hg > ζs .

T
12.4 Weir
The weir structure is a construction generating energy losses due to constriction of the flow.
The dimensions of a weir are described by a crest level and a crest width. Weirs are used
AF to regulate the flow in a waterway. A weir is treated as a general structure whose conceptual
description can be found in section 12.3. The input file format for a weir is described in
section C.12.1.

Table 12.4 lists the mapping of the weir input parameters to the general structure parameters
as well as default values for the remaining general structure parameters.

Table 12.4: Mapping table for weir input parameters to general structure parameters

General structure parameters Input variable/value for Weir

DR

zs crestLevel
zu1 , zu2 Upstream bedlevel of the channel
zd1 , zd2 Downstream bedlevel of the channel
ws , wu1 , wu2 , wd1 , wd2 crestWidth
µgf , µgd 1.0
cgf , cgd , cwf , cwd corrCoeff
gateLowerEdgeLevel 1010
gateHeight N/A
gateOpeningWidth N/A

During the simulation a number of checks and possibly corrections on some dimensions of
the weir are performed.
⋄ If the given crestLevel is below the bedlevel of the surrounding waterlevel points in
the channel, the crestLevel (zs ) is raised to the highest bedlevel of these two points
(also see footnote 1).
⋄ If the given crestWidth is larger than the corresponding maximum total flow width of
the underlying flow link(s) then the crestWidth is set to that maximum flow width.

Deltares 189 of 562

 Hydraulic structures

12.5 Gates
Constructions that partially block the horizontal flow can be modelled as so-called "gates". Its
horizontal and vertical position can be specified. Upstream of the gate the flow is accelerated
due to contraction and downstream the flow is decelerated due to expansion. A gate may in-
clude two type of openings, namely, in horizontal and in vertical directions. In two-dimensional
simulations, the vertical effect is parameterized by a quadratic energy loss term.

The horizontal effect is mimicked by setting the velocities of the computational faces (at posi-
tion of the gate) to zero. This generates structure of the horizontal flow around the gate which

T
is more realistic. There is no transport of salt or sediment through the blocked computational
faces of a gate. The width of a gate is an user defined parameters. If the user does not define
it, the width is assumed to be zero, so it has no influence on the water volume.

In D-Flow FM the gates can be imposed by polygons, and can be edited in a similar way
AF as the other structures. For more details on gates in the User Interface, we refer you to
section 7.4.2.10. In Figure 12.7 the geometric parameters of a gate are shown.
DR

Figure 12.7: Input for a gate

The structure of the input file for the gates is as follows:

type = gate
id = gate01
locationFile = gate01.pli
crestLevel = 7
gateLowerEdgeLevel = 15
gateOpeningWidth = gate01_opening_width.bc
gateHeight = 5
gateOpeningHorizontalDirection= symmetric
crestWidth =

Deltares 190 of 562

 Hydraulic structures

12.6 Orifice
The orifice structure can be used to simulate rectangle-shaped gates through which water
within a channel or river is led. Orifices are used to regulate the water flow through or towards
a channel or river. An orifice is treated as a general structure whose conceptual description
can be found in section 12.3. The input file format for an orifice is described in section C.12.8.

Table 12.5 lists the mapping of the orifice input parameters to the general structure parameters
as well as default values for the remaining general structure parameters.

Table 12.5: Mapping table for orifice input parameters to general structure parameters

T
General structure parameters Input variable/value for Orifice
zs crestLevel
zu1 , zu2 Upstream bedlevel of the channel
AF zd1 , zd2
ws , wu1 , wu2 , wd1 , wd2
Downstream bedlevel of the channel
crestWidth
µgf , µgd 1.0
cgf , cgd , cwf , cwd corrCoeff
gateLowerEdgeLevel gateLowerEdgeLevel
gateHeight 1010
gateOpeningWidth 0.0
DR

During the simulation a number of checks and possibly corrections on some dimensions of
the orifice are performed.
⋄ If the given crestLevel is below the bed level of the surrounding water level points in
the channel, the crestLevel (zs ) is raised to the highest bed level of these two points
(also see footnote 1).
⋄ If the given crestWidth is larger than the corresponding maximum total flow width of
the underlying flow link(s) then the crestWidth is set to that maximum flow width.
⋄ If the given gateLowerEdgeLevel is below the crestLevel, the gateLowerEdgeLevel
is set to that crestLevel.

Flow limiter
The total flow through an orifice can be limited using the input keywords (use)LimitFlowPos
and (use)LimitFlowNeg (in positive and negative direction, respectively). In this case
the discharge through this structure is limited to the maximum specified discharge. When an
orifice is located on a 2D grid, the flow limiter is applied for each flow link individually. The
maximum discharge through each individual orifice link is weighted by the individual sill width
of a link (ws (L)) divided by the total width at the sill (ws ):

Qlim (L) = min(Q(L), Qlim · ws (L)/ws ), (12.44)

where notation from section 12.3.2 is reused. As this limitation per link based on width is only
PN
an approximation, this can mean that L=1 Qlim (L) ≤ Qlim .

Deltares 191 of 562

 Hydraulic structures

12.7 Culvert
The culvert is an underground structure that normally connects two open channels. The flow
through a culvert is affected by its upstream and downstream invert levels (zc1 and zc2 , re-
spectively), its length, the size and shape of its closed cross section, its inlet loss, its friction
loss, its valve loss and its outlet loss. The input file format for a culvert is described in sec-
tion C.12.3.

Figure 12.8 shows a side view of a culvert.

ζ1

T
ζ2
zc1
AF L
Figure 12.8: Side view of a culvert
zc2

Two flow conditions can occur:

Free flow when ζ2 < zc2 + hc2

p
Q = µAf c 2g(ζ1 − (zc2 + hc2 )) (12.45)
DR

Submerged flow when ζ2 ≥ zc2 + hc2 :

p
Q = µAf c 2g(ζ1 − ζ2 ) (12.46)

Where:
Q Discharge through culvert [m3 /s]
µ Discharge coefficient, derived from loss-coefficients [−]
Af c Discharge culvert flow area min(Af c1 , Af cvalve ) [m2 ]
Af c1 : Flow area in the culvert at its upstream side [m2 ]
Af cvalve : Flow area under the culvert valve [m2 ]
g Acceleration due to gravity [m/s2 ] (≈ 9.81)
ζ1 Upstream water level [m]
ζ2 Downstream water level [m]
zc2 Downstream culvert invert level [m] p
hc2 Critical culvert depth at the downstream side, 3 Q2 /(gT22 ) [m]
T2 Surface width in the culvert at its downstream side [m]

A(hc2 )
T2 = (12.47)
hc2
A(hc2 ) Flow area of the culvert at water depth (hc2 ) [m2 ]

Deltares 192 of 562

 Hydraulic structures

Discharge coefficient (µ)

For numerical reasons the discharge coefficient (µ) is limited to a maximum of 1.0. The
discharge coefficient (µ) is computed as follows:
1
µ= p (12.48)
ξi + ξf + ξv + ξo

Where:
ξi Inlet loss coefficient [−]

T
ξf Friction loss coefficient [−]
ξv Valve loss coefficient [−]
ξo Outlet loss coefficient [−]

The inlet loss coefficient (ξi ) can be defined as a constant value only.
AF
The friction loss coefficient (ξf ) is computed as follows:
2gL
ξf = (12.49)
C12 R

Where:
L Length of the culvert [m]
C1 Chézy coefficient in the culvert at its upstream side [m1/2 /s]
R Hydraulic radius [m]
DR


Rc1 ζ1 ≥ zc1 + hvalve
R= (12.50)
Rvalve ζ1 < zc1 + hvalve
hvalve Valve opening height [m]
Rc1 Hydraulic radius in the culvert at its upstream side [m]
Rvalve Hydraulic radius based on actual valve opening height [m]
zc1 Upstream culvert invert level [m]

The valve loss coefficient (ξv ) can be defined as a function of the ratio of the “Valve opening
height” and the “maximum inner culvert height”.

Remarks:
⋄ During the computations the actual valve loss coefficient (ξv ) is derived from the user
defined table, while using the ratio of the “actual valve opening height (hvalve ) and the
“actual maximum inner culvert height” (hculvert ):
ξv = f (hvalve /hculvert ) (12.51)
Where f is a piecewise linear function with support points defined by the input fields
relOpening and lossCoeff.
⋄ A constant extrapolation is performed for values outside of the range of relOpening.

The outlet loss coefficient (ξo ) is computed as follows:

⋄ Submerged flow (ζ2 = zc2 + hc2 ):

 2
Af c
ξo = k 1 − (12.52)
Af r2

Deltares 193 of 562

 Hydraulic structures

Where:
k User defined constant outlet loss coefficient [−]
Af r2 Flow area in the branch, adjacent to the downstream culvert side [m2 ]
Af c Culvert flow area [m2 ]

Afcvalve h1 ≥ zc1 + hgate
Af c = (12.53)
Afc1 h1 < zc1 + hgate

hvalve Valve opening height [m]

T
zc1 Upstream culvert invert level [m]
Afcvalve Flow area under the culvert valve [m2 ]
Afc1 Flow area in the culvert at its upstream side [m2 ]
⋄ Free flow (ζ2 < zc2 + hc2 ):
AF ξo = 0 (12.54)

Culvert cross sections, bed friction

For a culvert all available closed cross section types can be used. Culvert friction can be
specified using any of the available bed friction formulations.

Culvert, Good modelling practice aspects

During the simulation a number of checks and possibly corrections on some dimensions of
the culvert are performed.
DR

⋄ If the upstream invertLevel is below the bed level of the upstream water level point in
the channel, the bed level of this water level point is lowered to the upstream invertLevel.
⋄ If the downstream invertLevel is below the bed level of the downstream water level
point in the channel, the bed level of this water level point is lowered to the downstream
invertLevel.

Notice that the culvert checks are an exception to the other structure checks: the surrounding
bed levels are adjusted, whereas for all other structure, the structure’s own bed level(s) are
adjusted.

Figure 12.9: Good modelling practice, culvert, Inverted Siphon and Siphon

Deltares 194 of 562

 Hydraulic structures

Inverted siphon
The inverted siphon is a special version of the culvert. An inverted siphon is a structure that
normally connects two open channels, that are separated by a particular infrastructural work
(e.g. dike, railroad). The inverted siphon makes an underground connection through such
infrastructural work. An inverted siphon is assumed to be fully filled with water at its deepest
point. In case this does not yield for your stucture, you can consider to use a culvert. The
flow through an inverted siphon is affected by its upstream and downstream invert level, the
size and shape of its closed cross section, its ground layer thickness, its entrance loss, friction
loss, its valve loss, losses due to its bends (bend loss), and its exit loss.

T
AF
Figure 12.10: Side view of an inverted siphon

The bend losses are taken into account by changing Equation (12.55) into:

1
µ= p (12.55)
DR

ξi + ξf + ξv + ξo + ξb

Where:
ξb bend losses coefficient [−]

12.8 Long Culvert

12.8.1 Long culvert

Remark:
⋄ Long culvert functionality has beta status, and is still undergoing validation.

The long culvert is an underground pipe structure that normally connects two open waters
modeled as 2D grid cells. The difference with the normal culvert is that the long culvert is
modelled as pipe with a certain length, instead of being modelled as a subgrid culvert, with
only energy losses at the snapped flow link of the culvert. The long culvert stores actual
volume, and can optionally have multiple pressure points (which allows for a ’siphon-like’
geometry with varying bed levels). A culvert is only available in 1D2D modelling, while a
long culvert can be applied both in 1D2D and in 2D3D.

The flow through a long culvert is affected by its upstream and downstream invert levels (first
and last z -coordinate, respectively), its total length, the size of its closed rectangular cross
section, its friction loss, and its valve loss. The input file format for a long culvert is described
in Section C.12.4.

Deltares 195 of 562

 Hydraulic structures

Long culvert positioning

Figure 12.11 shows a side view of a long culvert. In the most simple case there will only be
two points z1 and z2 .

ζup
ζdown

zk zk+1

T
Figure 12.11: Side view of a culvert
AF Remark:
⋄ Long culvert functionality in 2D3D does not support parallel computing. Thus, parallel
model simulations with long culverts are only possible in D-Flow FM 1D2D.

Long culvert conversion from 2D3D to 1D2D

If it is desired to run a model containing long culverts in parallel (partitioned, using MPI), only
1D2D long culverts are supported. In order to facilitate this, a command line option is available
to convert a model containing old-style long culverts to the 1D2D implementation.
This is done with the --convertlongculverts command line option, as follows:
DR

dflowfm-cli.exe --convertlongculverts <prefix> <mdufile>

The prefix is a user defined input string that will be prepended to the new model input
files generated by the conversion process. The mdufile is an MDU file pointing to a net
file that does not yet contain the 1D2D culverts links, and also pointing to a structure file,
where the long culverts are defined via polyline coordinates. The conversion process reads
the polyline that defines the original long culvert, and creates a network branch representing
it. The original long culvert implementation allows for short long culverts that consist of a
single 2D2D link.

12.9 Bridges in 1D
This section contains a description of bridges in 1D. For modelling of bridge pillars in 2D we
refer to section 7.4.2.11

The bridge structure is a structure that can be used to model the flow underneath a bridge
(and across). The bridge’s geometry is defined by either or both of:
⋄ An abutment definition (as a cross section definition), which determines its wetted flow
area and hydraulic radius. The flow area of the bridge should be smaller than the sur-
rounding flow area of the channel.
⋄ A pillars definition.

A bridge definition has to consist of at least one geometry definition, so at least an abutment
definition or pillars definition has to be given in the input.

Deltares 196 of 562

 Hydraulic structures

Figure 12.12 shows an example bridge where flow area is restricted by abutments, the bridge
deck and two bridge pillars.

T
Figure 12.12: A suspension bridge

A limitation of the bridge structure is, that no free flow over the bridge can be computed. If
AF
free flow occurs over the bridge, it is advised to use a weir instead.

The general description of the discharge through a bridge is given by:

p
Q = µAf 2g(ζ1 − ζ2 ) (12.56)

Where
Q Discharge through bridge [m3 /s]
µ Discharge coefficient derived from loss-coefficients [-] (see Equation (12.57))
Af Wetted area [m2 ] of flow through bridge at upstream side
DR

g Acceleration due to gravity [m/s2 ] (≈ 9.81)

ζ1 Upstream water level [m]
ζ2 Downstream water level [m]

For the bridge the discharge coefficient is defined as:

!
1
µ = max 1, p (12.57)
ξi + ξf + ξo + ξy

Where
ξi Entrance loss coefficient.
ξf Friction loss coefficient.
ξo Exit loss coefficient.
ξy Pillar loss coefficient.

Remark:
⋄ For numerical reasons (e.g. validity of structure Equation (12.56)) the discharge coef-
ficient (µ) is limited to a maximum of 1.0. In other words, if µ, according to Equa-
tion (12.57) becomes larger than 1.0, the actual applied discharge coefficient in Equa-
tion (12.56) is capped at 1.0. This means that for a given discharge, the water level
difference over such bridge might be larger than anticipated, when considering the de-
fined friction loss coefficients.

Deltares 197 of 562

 Hydraulic structures

Abutment bridge
By defining an abutment bridge, the coefficients ξi , ξf and ξo in Equation (12.57) get a non-
zero value. Also the flow area through the bridge is affected by the additional cross section
definition.

When desired, the bridge deck can affect the flow through the bridge, for example by having
the cross section closed. A limitation however, is that flow over the bridge deck cannot be
taken into account.

The ξi loss coefficient is an input parameter

T
The ξo coefficient is defined as:
 2
Af
ξo = k 1 − , (12.58)
AF
where
Af2

k Constant exit loss coefficient

Af Wetted area [m2 ] of flow through bridge at upstream side, including the bridge
pillars.
A f2 Wetted area [m2 ] of flow in branch at downstream side of bridge

The ξf coefficient is defined as:

2gL
DR

ξf = , (12.59)
C 2R
where
g Acceleration due to gravity [m/s2 ] (≈ 9.81)
L Length of bridge [m]
C Chézy coefficient [m1/2 /s]
R Hydraulic radius [m]

During the simulation a check and possibly correction on the vertical position of the bridge
can be performed, see MDU option ChangeStructureDimensions:
⋄ If the bed level of the bridge is below the bed level of the surrounding water level points in
the channel, the bedlevel of the bridge is raised to the highest bed level of the two water
level points (also see footnote 1).
⋄ In case the bed level is raised, the complete cross section is also raised.

Pillars
A bridge can have one or more pillars that affect the discharge through the bridge. By defining
pillars, the coefficient ξy in Equation (12.57) get a non-zero value:

αy
ξy = β , (12.60)
Af
where
β Parameter [−] depending on shape of pillar [s] (shape factor). Normally be-
tween 0.22 and 1.56
Af Wetted area [m2 ] of flow through bridge at upstream side

Deltares 198 of 562

 Hydraulic structures

αy Area [m2 ] of wetted part of pillar [s] perpendicular to the flow direction, consid-
ered at upstream side

12.10 Universal weir

The universal weir structure is a construction generating energy losses due to constriction of
the flow. The geometrical shape of the universal weir’s crest can be defined as a Y-Z profile
(see Figure 12.13).
It is assumed that the discharge across a universal weir is the summation of the discharges
across each individual weir section. A weir section is the space between to subsequent sup-

T
port point of the Y-Z profile.

The crest level profile of a universal weir is divided into:

⋄ rectangular weir sections, having a horizontal bed and
⋄ triangular weir sections, having a sloping bed.
AF Rectangular weir sections are considered as a broad-crested weir. Triangular weir sections
are considered as (the half of) a broad-crested weir with truncated triangular control section
(Bos, 1989).
DR

Figure 12.13: Crest level (Y-Z) profile of a Universal weir, divided into three rectangular
weir sections (2, 4 and 6) and four triangular weir sections (1, 3, 5 and 7)

Parameters depicted in Figure 12.13 are:

Ai Flow area of section i [m2 ]
Wi Width of weir section i [m]
zi,left Elevation at the left side of weir section i [mAD ]
zi,right Elevation at the right side of weir section i [mAD ]
zCrest Crest level of the Universal weir (output parameter only), equal to the lowest
elevation of its crest level profile [mAD ]
ζ Water level [mAD ]

Deltares 199 of 562

 Hydraulic structures

Following equations yield for a universal weir:

N
X N
X
Q= (ui Ai ) = Qi (12.61)
i i
N
X
A= Ai (12.62)
i

Ustructure = Q/A (12.63)

T
where:
A Flow area of the universal weir [m2 ]
Ai Flow area of weir section i [m2 ]
AF
N
Q
Qi
Number of weir sections i [−]
Discharge over the universal weir [m3 /s]
Discharge over weir section i [m3 /s]
ui Flow velocity in weir section i [m/s]
Ustructure Average flow velocity over the universal weir [m/s]

Following equations yield for a rectangular weir section i:

zi,crest = min(zi,left , zi,right ) (12.64)
DR

mlrectangular ,i = 2/3 (12.65)

 
ζ −z
⋄ Free rectangular weir flow if ζ12 −zi,crest
i,crest
≤ mlrectangular ,i
r
2 p
ui = ce g ζ1 − zi,crest (12.66)
3
2
Ai = Wi (ζ1 − zi,crest ) (12.67)
3 r
2 2
Qi = ui Ai = ce g Wi (ζ1 − zi,crest )3/2 (12.68)
3 3
 
ζ −zi,crest
⋄ Submerged rectangular weir flow if ζ12 −zi,crest > mlrectangular ,i
p
ui = ce 2g(ζ1 − ζ2 ) (12.69)
Ai = Wi (ζ2 − zi,crest ) (12.70)
p
Qi = ui Ai = ce Wi (ζ2 − zi,crest ) 2g(ζ1 − ζ2 ) (12.71)

Following equations yield for a triangular weir section i:

zi,crest = min(zi,left , zi,right ) (12.72)

dzi = |zi,left − zi,right | (12.73)


4

5 if (ζ1 − zi,crest )) ≤ 1.25 dzi
mltriangular ,i = (12.74)
2 + 1 dzi
if (ζ1 − zi,crest )) > 1.25 dzi

3 6 (ζ1 −zi,crest )

Deltares 200 of 562

 Hydraulic structures

 
ζ2 −zi,crest
⋄ Free triangular weir flow if ζ1 −zi,crest
≤ mltriangular ,i
q
ui = ce 2g(1 − mltriangular ,i )(ζ1 − zi,crest ) (12.75)

  
(mltriangular ,i (ζ1 −zi,crest ))2 ζ1 −zi,crest


 Wi 2 dzi
if 1/mltriangular ,i
≤ dzi
Ai =   (12.76)
ζ1 −zi,crest ζ1 −zi,crest
 dzi
Wi − > dzi

1/mltriangular ,i 2
if 1/mltriangular ,i

T
Qi = ui Ai (12.77)
 
ζ2 −zi,crest
⋄ Submerged triangular weir flow if ζ1 −zi,crest
> mltriangular ,i
AF ui = ce
p
2g(ζ1 − ζ2 ) (12.78)

  
(ζ2 −zi,crest )2
Wi

2 dzi
if ζ2 − zi,crest ≤ dzi
Ai = (12.79)
 dzi
Wi (ζ2 − zi,crest − ) ζ2 − zi,crest > dzi

2
if

Qi = ui Ai (12.80)
DR

where:
Ai Flow area of weir section i [m2 ]
ce Discharge coefficient, applicable to all rectangular weir sections as well as to all
triangular weir sections of a universal weir [−]
dzi Vertical distance between the elevation at the left side and the right side of a
triangular weir section i [m]
g Acceleration due to gravity [m/s2 ] (≈ 9.81)
mlrectangular ,i Water-level-based modular limit of a rectangular weir section i. Its value is
always equal to 2/3 [−]
mltriangular ,i Water-level-based modular limit of a triangular weir section i. Its value de-
pends on the actual water depth. [−]
Qi Discharge over weir section i [m3 /s]
ui Velocity in weir section i [m/s]
Wi Width of weir section i [m]
zi,crest Crest level of weir section i [mAD ]
zi,left Elevation at the left side of weir section i [mAD ]
zi,right Elevation at the right side of weir section i [mAD ]
ζ1 Water level at the upstream side of the universal weir [mAD ]
ζ2 Water level at the downstream side of the universal weir [mAD ]

During the simulation a check and possibly correction on the crest level of the universal weir
is performed.
⋄ If the bed level of the bridge is below the bed level of the surrounding water level points in
the channel, the bed level of the bridge is raised to the highest bed level of the two water
level points (also see footnote 1).
⋄ In case the bed level is raised, the complete weir profile is also raised.

Deltares 201 of 562

 Hydraulic structures

12.11 Pump
The pump structure forces the flow of water in one direction at a certain discharge. This
discharge is essentially a predescribed value for the pump, depending on the type of pump. A
pump can either be a staged pump or a non staged pump. The input file format for a pump is
described in section C.12.7.

A staged pump contains control rules to switch on or off the pump and to set the actual
capacity depending on the water levels at both sides of the pump.

T
A non-staged pump has its capacity prescribed directly. The capacity can be defined as a
constant value, a time series or controlled by RTC.

Both types of pumps can optionally have a reduction factor table defined. When a pump
pumps against a bigger head difference, its effective discharge may be lower than the maxi-
AF
12.11.1
mum capacity.

Notation
The used variable in this section are described below.
n
ζss Water level at the suction side of the pump at the current time level.
n
ζds Water level at the delivery side of the pump at the current time level.
hnss Water depth at the suction side of the pump at the current time level.
Vssn Water volume at the suction side of the pump at the current time level.
DR

12.11.2 Orientation
Water is always pumped from the suction side to the delivery side. The orientation of the
pump in the model is defined by either the branch orientation (1D) or the direction of the
polyline (2D, see section C.12). It may be convenient to orientate the pump opposite to the
branch orientation of the channel. This is controlled by the input parameter orientation.
positive means the suction side is at the (geometrical) upstream side of the pump and
negative means that the suction side is at the (geometrical) downstream side of the pump.

12.11.3 Staged pump

Pump discharge
Suction-side Delivery-side
ζds
ζss ζoff
ζon ζon
ζoff

Figure 12.14: Pump station

Deltares 202 of 562

 Hydraulic structures

Pump stages
A pump station may consist of multiple pump stages. Each stage can have a different pump
capacity and switch on and switch off level. At each point in time, the pump can be in one
pump stage only. The highest stage that is turned on, will be the actual stage, regardless of
the state of the lower stages.

The pump can be controlled at either the suction side only, the delivery side only or on both
sides.

T
The state of pump stagei is determined by:
⋄ suction side:
if no suction side control then sn+1
ss,i = True
⋄ ⋄ ⋄ ⋄

n
else if ζss > ζss,on,i then sn+1
ss,i = True
AF else sn+1
n
else if ζss < ζss,off ,i then sn+1
n
ss,i = sss,i
ss,i = False

⋄ delivery side:
if no delivery side control then sn+1
ds,i = True
⋄ ⋄ ⋄ ⋄

n
if ζds < ζds,on,i then sn+1
ds,i = True
n
else if ζds > ζds,off ,i then sn+1
ds,i = False
else sn+1 n
ds,i = sds,i

⋄ if sn+1 n+1
ss,i == True and sds,i == True then pump stagei is on
DR

Where:
sn+1
ss,i Denotes whether the suction side control for the next time step is on (True ) or
off (False ).
sn+1
ds,i Denotes whether the delivery side control for the next time step is on (True ) or
off (False ).
ζss,on,i Start level at suction side for stage i.
ζss,off ,i Stop level at suction side for stage i.
ζds,on,i Start level at delivery side for stage i.
ζds,off ,i Stop level at delivery side for stage i.

Subsequently, the actual pump stage will be set to the stage with the highest sequence num-
ber that is turned on.

12.11.4 Non-staged pump

A non staged pump has either a constant capacity, a time series for the capacity or can be
controlled by an external process, such as real time control.

Deltares 203 of 562

 Hydraulic structures

12.11.5 Capacity reduction table

A capacity reduction table can be defined both for the staged and non-staged pump. The
capacity reduction table contains capacity reduction factors as a function of the pump head
(i.e., ζds − ζss ). The pump heads (key ’head’ in input) in a capacity reduction table should be
in increasing order. Capacity reduction factors (key reductionFactor in input) should be
equal or larger than 0 and equal or less than 1. The actual pump discharge equals the current
pump capacity multiplied by the capacity reduction factor. When no capacity reduction table
is defined, in effect a capacity reduction factor equal to 1 is applied.

Please note that the pump head at t = tn is used to determine the capacity reduction factor

T
to be applied in the time-step from t = tn to t = tn+1 .

12.11.6 Distribution and relaxation of pump discharge

AF A single pump in a 2D model may span multiple flow links, in which case the pump discharge is
distributed evenly over the included flow links. Flow links are included when the water depth at
the suction side is above a certain threshold: hn ss > 0.01. A single, representative water level
at the suction side is then determined by averaging the separate water levels at the suction
side of the pump over the included flow links. The delivery side water level is determined
similarly. These two values are used for staged pumps or, optionally, for a capacity reduction
table.

The actual pump discharge may be limited (relaxed) even further when total potential pump
volume is above the total available volume of water at the suction side. In other words, it can
happen that the actual discharge through the pump is limited below capacity by water volume
DR

on suction side because the suction side has not enough volume of water to be sucked.

The actual discharge is computed by:

X
n
qpump = min(qpump , 0.9 · Vssn /∆tn ). (12.81)
open pump links

The pump capacity is then equally distributed over the open pump links.

12.12 Compound structure

A compound structure consists of several structures (structure elements) parallel to each other
at the same location. See Table C.12 for a list of possible structure types. The only exception
is that compound structures cannot be nested. Each structure element in a compound is
treated independently. The discharge through each structure element is then summed up to
the total discharge for the compound structure.

The user should keep in mind that geometric checks on structure parameters are performed
for each structure element independently. For example the total structure width might be larger
than the actual width of the channel, even though the widths of the underlying structures have
been checked. As a result the user must be extra careful to check for inconsistencies in the
input.

12.13 Thin dams

Thin dams are similar to fixed weirs. The only difference between the thin dams and fixed
weirs are in their crest levels. Thin dams, in principle, include infinitely high crest levels and
hence, they do not allow water flux. Similar to the other structures, the thin dams can be

Deltares 204 of 562

 Hydraulic structures

selected from the toolbar and drawn by a polygon. D-Flow FM adjusts the polygon to the
nearest velocity points. The input data for a thin dam is identical to those for fixed-weir, except
for the crest level.

12.14 Floating structures (via ice modelling)

A floating structure isn’t available in D-Flow FM, like a floating structure in Delft3D-FLOW.
However, in D-Flow FM an adequate alternative is available, namely via prescribing an ice
thickness. An ice block in D-Flow FM has a similar effect as a floating structure in Delft3D-
FLOW. It pushes down the water level at the location of the ice block or the floating structure

T
due to its pressure. For an example how to apply this in a D-Flow FM model, see the example
and the description in section 16.8.1 ("Ice modelling via External"). In this way, a floating
structure in a D-Flow FM model can be mimicked.
AF
DR

Deltares 205 of 562

 13 Bedforms and vegetation
The terrain and vegetation exert shear stresses on the passing flow. The magnitude of the
shear stress of the bed is often characterised by means of roughness coefficient of type
Chézy, Manning or White-Colebrook. Within the main stream flow the shear stresses are
largely determined by the local conditions of the alluvial bed (bed composition and bedform
characteristics). In other areas, such the floodplains of rivers and in the intertidal areas of
estuaries, the flow resistance is determined by a combination of vegetation and an alluvial
bedforms or even a non-alluvial bed. To accurately represent such conditions in the numer-
ical model, D-Flow FM has been extended with a coupled of features, this includes bedform

T
roughness predictors and vegetation models. These types of flow resistance may be resolved
in a 2D numerical model using the trachytope approach (see section 13.2).

13.1 Bedform heights

AF The dune height and Van Rijn (2007) bedform roughness predictors are not yet documented.
They will be in an upcoming release.

13.2 Trachytopes
This functionality allows you to specify the bed roughness and flow resistance on a sub-grid
level by defining and using various land use or roughness/resistance classes, further referred
to as trachytopes after the Greek word τραχύτ ης for roughness. The input parameters and
files to use the trachytopes functionality are described in section C.7.

At every time step (or less frequent as requested by the user) the trachytopes are converted
DR

into a representative bed roughness C , k or n and optional linear flow resistance coefficient
λ per velocity point with index j .
1
M = − λj uj |uj | (13.1)
2

To save computational time the user may choose to update the computed bed roughness and
resistance coefficients less frequently than every time step. See section C.7 for a description
of the keywords and input files associated with this feature.

The following two sections describe the various classes of trachytopes distinguished and the
way in which they are combined, respectively.

13.2.1 Trachytope classes

Three base classes of trachytopes are distinguished: area classes, line classes and point
classes. The area classes (type range 51–200) basically cover the whole area, therefore,
they are generally the dominant roughness factor. The line classes (type range 201–250)
may be used to represent hedges and similar flow resistance elements; it will add anisotropy
to the roughness field. The point class (type range 251–300) represents a set of point flow
resistance elements. The next six sections provide an overview of the various trachytope
formulae implemented.

Special classes (1–50)

In addition to the three base classes two special trachytope classes have been defined: a flood
protected area and a composite trachytope class. The first class represents a sub-grid area
that is protected from flooding and thus does not contribute to the bed roughness; however,

Deltares 206 of 562

 Bedforms and vegetation

the effect on the flow resistance should be taken into account. The second class can be used
to make derived trachytope classes that are a combination of two other trachytopes: an area
fraction α of trachytope type T1 and an area fraction β (often equal to 1 − α) of trachytope
type T2 .

FormNr Name Formula

Special classes (1–50)

T
1 flood protected area area fraction shows up as fb in Eqs. 13.53 and
13.56

2 composite trachytope fraction α of type T1 and fraction β (generally

β = 1 − α) of type T2
AF
Area trachytope classes (51–200)
The class of area trachytopes is subdivided into three types: simple (51–100), alluvial (101–
150) and vegetation (151–200). Four simple area trachytopes have been implemented repre-
senting the four standard roughness types of flow module.

FormNr Name Formula

51 White-Colebrook value k
DR

52 Chézy value C
√
53 Manning value C = 6 h/n
54 z0 value k = 30z0

Six alluvial trachytopes have been implemented.

FormNr Name Formula

101 simplified Van Rijn Equation (13.2)

102 power relation Equation (13.3)
103 Van Rijn (1984) Equations 13.4 to 13.12
104 Struiksma Equations 13.13 to 13.16
105 bedforms quadratic Equation (13.17)
106 bedforms linear Equation (13.18)

The first alluvial roughness formula is a simplified version of the Van Rijn (1984) alluvial rough-
ness predictor
h −0.3
i
k = Ah0.7 1 − e−Bh (13.2)

it is obtained from Equation (13.4) by noting that hb ∝ h0.7 and Lb ∝ h and ignoring the
grain related roughness. The parameters A and B can be calibrated by the user. The second
formula implemented is a straightforward general power law

C = AhB (13.3)

Deltares 207 of 562

 Bedforms and vegetation

where A and B are calibration coefficients. The Van Rijn (1984) alluvial roughness predictor
reads

k = k90 + 1.1hb 1 − e−25hb /Lb

(13.4)

where the bedform height hb and length Lb are given by

 0.3
D50
1 − e−T /2 (25 − T )


hb = 0.11h (13.5)
h
Lb = 7.3h (13.6)

T
where h is the local water depth and the transport stage parameter T is given by

u′ 2∗ − u2∗,cr
T = (13.7)
u2∗,cr
AF
where u′ ∗ is the bed shear velocity given by
2
u′ ∗ = gu2 /Cg,90
2
(13.8)

where

Cg,90 = 18 10 log(12h/k90 ) and k90 = 3D90 (13.9)

and u∗,cr is the critical bed shear velocity according Shields given by

u2∗,cr = g∆D50 θc (13.10)

DR

given


 0.24/D∗ if D∗ ≤ 4

−0.64
if 4 < D∗ ≤ 10

 0.14D∗


θc = 0.04D∗−0.10 if 10 < D∗ ≤ 20 (13.11)

0.013D∗0.29 if 20 < D∗ ≤ 150





 0.055 if 150 < D∗

where
 1/3
g∆
D∗ = D50 (13.12)
ν2
This predictor does not contain any calibration coefficients but requires D50 and D90 data
from the morphology module. It does not include the advective and relaxation behaviour that
is available by explicitly simulating the dune height as described in section 13.1 combined with
trachytope number 106.

The second alluvial roughness predictor proposed by (Struiksma, pers. comm.) allows for a
lot of adjustments, it reads

1 1 1
2
= (1 − ξ) 2 + ξ 2 (13.13)
C C90 Cmin
where

C90 = A1 10 log(A2 h/D90 ) (13.14)

Deltares 208 of 562

 Bedforms and vegetation

and
2
max(0, θg − θc ) θm − θc θg
ξ= (13.15)
θm − θc (θm − θc )θg
which varies from 0 at θg ≤ θc to 1 at θg = θm where

u2
θg = 2
(13.16)
C90 ∆D50
and A1 , A2 , θc , θm , Cmin are coefficients that the user needs to specify. This formula requires

T
also D50 and D90 data from the morphology module. The fifth formula is based on Van Rijn
(2007) and reads
q
2 + k2 2 h
k = min( ks,r s,mr + ks,d , ) (13.17)
2
AF
It uses the roughness heights of ripples kr , mega-ripples kmr and dunes kd . These formulae
depend on sediment properties D50 and D90 data which may be either specified as part of
the roughness type or obtained from the morphology module. The sixth formula is similar, but
uses a linear addition
h
k = min(ks,r + ks,mr + ks,d , ) (13.18)
2

Four vegetation based area trachytopes have been implemented. Two formulae (referred to
as ‘Barneveld’) are based on the work by Klopstra et al. (1996, 1997) and two on the work by
DR

Baptist (2005).

FormNr Name Formula

151 Barneveld 1 Eqs. 13.19 – 13.28, CD = 1.65

152 Barneveld 2 Eqs. 13.19 – 13.25, 13.29 – 13.31
153 Baptist 1 Eqs. 13.32 and 13.33
154 Baptist 2 Eqs. 13.34, 13.36 and 13.37

The formula by Klopstra et al. (1997) reads

 q  
√ p

 √2 h
C3 e v 2A 2
+ uv0 − C3 + uv0 + 2 

 2A 
√ √

 

√
1 
 
( C3 ehv 2A +u2v0 −uv0 )( C3 +u2v0 +uv0 )
C = 3/2 u
√ v0
ln √ h √2A 2 √ +
h  2A ( C3 e v +uv0 +uv0 )( C3 +u2v0 −uv0 )
√
 

       
g(h−(hv −a))
 h−(hv −a)

a
(h − (h − a)) ln − a ln − (h − h )

 

κ v z0 z0 v

(13.19)

where
nCD
A= (13.20)
2α

2g(h − hv )
C3 = √ √ √ (13.21)
α 2A(ehv 2A + e−hv 2A )

Deltares 209 of 562

 Bedforms and vegetation

q
4E12 κ2 (h−hv )
1+ 1+ g
a= 2E12 κ2
(13.22)
g

and

z0 = ae−F (13.23)

T
where
√ √
2AC3 ehv 2A
E1 = q √
(13.24)
2 C3 ehv 2A + u2v0
AF
and
q √
κ C3 ehv 2A + u2v0
F = p (13.25)
g(h − (hv − a))

Here, h is the water depth, hv is the vegetation height, and n = mD where m is the number
of stems per square metre and D is the stem diameter. For the first implementation the
parameter α in Equation (13.21) is given by
DR

p
α = max(0.001, 0.01 hhv ) (13.26)
√
and the velocity within the vegetation is approximated by uv0 i where
2g
u2v0 = (13.27)
CD n
and i is the water level gradient. For emerged vegetation the first implementation reads

1 CD nh
2
= (13.28)
C 2g

The second implementation of Klopstra et al. (1996) is based on a modification by Van Velzen
et al. (2003); it is identical except for the following modifications to Eqs. 13.26 – 13.28. The
main difference between the two implementations is the inclusion of the roughness Cb of the
bed itself (without vegetation). The parameter α in Equation (13.21) is now given by

α = 0.0227h0.7
v (13.29)
√
and the velocity within the vegetation is approximated by uv0 i where
hv
u2v0 = CD hv n 1
(13.30)
2g
+ Cb2

and i is the water level gradient. For emerged vegetation the second implementation reads

1 CD nh 1
= + (13.31)
C2 2g Cb2

Deltares 210 of 562

 Bedforms and vegetation

For large values of Cb the latter two equations simplify to the corresponding equations of the
first implementation. The first implementation requires vegetation height hv and density n
as input parameters (the drag coefficient CD is equal to 1.65); for second implementation
you’ll also need to specify the drag coefficient CD and the alluvial bed roughness kb (Cb in
Equation (13.31) is computed as 18 10 log(12h/kb )).

The first implementation of the roughness predictor by Baptist (Baptist, 2005) reads for the
case of submerged vegetation
√
1 g h
C=q + ln( ) (13.32)

T
1
+ CD nhv κ hv
Cb2 2g

where n is the vegetation density (n = mD where m is the number of stems per square
metre and D is the stem diameter). The second term goes to zero at the transition from
submerged to emerged vegetation. At that transition the formula changes into the formula for
AF
non-submerged vegetation which reads

C=q
1
(13.33)
1 CD nh
Cb2
+ 2g

which is identical to the non-submerged case of the second implementation of the work by
Klopstra et al. (1996) (see Equation (13.31)).

The drawback of the three vegetation based formulations above is that they parameterize the
flow resistance by means of the bed roughness. Consequently, the presence of vegetation
DR

will lead to a higher bed roughness and thus to a higher bed shear stress and larger sediment
transport rates in case of morphological computations. Therefore, we have included a − λ2 u2
term in the momentum equation where λ represents the flow resistance of the vegetation. For
the case of non-submerged vegetation h < hv the flow resistance and bed roughness are
strictly separated

C = Cb and λ = CD n (13.34)

In the case of submerged vegetation h > hv the two terms can’t be split in an equally clean
manner. However, we can split the terms such that the bed shear stress computed using
the depth averaged velocity u and the net bed roughness C equals the bed shear stress
computed using the velocity uv within the vegetation layer and the real bed roughness Cb .

u2 u2v
= (13.35)
C2 Cb2

With this additional requirement we can rewrite Equation (13.32) as

√ s
g h CD nhv Cb2
C = Cb + ln( ) 1+ (13.36)
κ hv 2g
and
hv Cb2
λ = CD n (13.37)
h C2
which simplify to Equation (13.34) for h = hv . Both formulae by Baptist require vegetation
height hv , density n, drag coefficient CD and alluvial bed roughness Cb as input parameters.

Deltares 211 of 562

 Bedforms and vegetation

Linear trachytope classes (201–250)

Two formulae have been implemented for linear trachytopes such as hedges or bridge piers.

FormNr Name Formula

201 hedges 1 Eqs. 13.38 to 13.40

202 hedges 2 Eqs. 13.41 to 13.43

T
The first implementation reads

1 h Lhedge 1 − µ2
= (13.38)
C2 2g Wcell Lcell µ2
AF
where Lhedge is the projected length of the hedge, Wcell and Lcell are the width and length
of the grid cell. The ratio Lhedge /Wcell may be interpreted as the number of hedges that the
flow encounters per unit width. The second ratio is thus the inverse of the average distance
between these hedges within the grid cell. The last term may be loosely referred to as the
drag of the hedge, which is determined by the hedge pass factor µ given by
 
h
µ = 1 + 0.175n −2 (13.39)
hv
if the hedge extends above the water level (hv > h) and is given by
DR

 
h
µ = 1 − 0.175n (13.40)
hv
if the hedge is fully submerged (h > hv ) where n is a dimensionless hedge density. The
second implementation reads

1 CD nLhedge h
2
= (13.41)
C 2gLcell Wcell
or equivalently
s r 
2gLcell Wcell 1
C= (13.42)
hLhedge CD n

for non-submerged conditions and

 v 
h−hv 2
s r u

2gLcell Wcell  hv 1 u
h
C= + m0 t
2  (13.43)
hLhedge h CD n 1 − h−h v
h

for submerged conditions. We recognize the same ratio Lcell Wcell /Lhedge that represents
the average distance between hedges. Equation (13.41) can be directly compared to similar
equations for area trachytopes (Equation (13.28)), point trachytopes (Equation (13.44)). Note
that the formula for computing the loss coefficient for a bridge explicitly includes the reduction
in the flow area and the resulting increase in the effective flow velocity, whereas the above
mentioned trachytope formulae don’t.

Deltares 212 of 562

 Bedforms and vegetation

Point trachytope classes: various (251–300)

One formula for point trachytopes has been implemented. It may be used to represent groups
of individual trees or on a smaller scale plants.

FormNr Name Formula

251 trees Eqn. 13.44

T
The implemented formula reads
s
2g
C= (13.44)
CD n min(hv , h)
where n = mD with m the number of trees per unit area and D the characteristic tree
AF diameter, hv is the vegetation height and h is the local water depth. The formula is identical
to Equation (13.33) except for the fact that the point trachytope formula has no bed roughness
and area associated with it. The generalization of Equation (13.44) to the submerged case
(h > hv ) lacks the extra term in Equation (13.32).

13.2.2 Averaging and accumulation of trachytopes

Point and linear roughnesses are accumulated by summing the inverse of the squared Chézy
values Ci .
1 X 1
DR

2
= 2
(13.45)
Cpnt i
Cpnt,i
1 X 1
2
= 2
(13.46)
Clin i
Clin,i

The area roughnesses are accumulated weighted by the surface area fraction fi . These
roughnesses are accumulated as White-Colebrook roughness values and as Chézy values;
for the latter values both the linear sum (“parallel”) and the sum of inverse of squared values
(“serial”) are computed. Roughness values are converted into each other as needed based
on the local water depth.
X
karea = fi ki (13.47)
i
1 X 1
= fi (13.48)
2
Carea,s i
Ci2
X
Carea,p = fi Ci (13.49)
i

For the fraction of the grid cell area for which no roughness class is specified the default
roughness is used, via keywords UnifFrictCoef and UnifFrictType.

The flow resistance coefficients are also accumulated proportionally to the surface area frac-
tion fi associated with the trachytope considered. For the fraction of the grid cell area for
which no flow resistance is specified, obviously none is used.
X
λ= fi λi (13.50)
i

Deltares 213 of 562

 Bedforms and vegetation

The final effective bed roughness of the grid cell may be computed by either one of the follow-
ing two methods.

Method 1
The total mean roughness is computed by summing the White-Colebrook values for the areas
and line and point resistance features.

km = karea + klin + kpnt (13.51)

T
where klin = 12h10−Clin /18 and kpnt = 12h10−Cpnt /18 . The effect of the water free
area fraction fb is taken into account by means of the following empirical relation in which
Cm = 18 10 log(12h/km ) is the mean Chézy value corresponding to the total mean White-
Colebrook roughness value obtained from Equation (13.51).
AF fb = max(min(0.843, fb ), 0.014)
 p 
Ctotal = Cm 1.12 − 0.25fb − 0.99 fb
(13.52)

(13.53)

The resulting Ctotal value is used in the computation. This method together with trachytope
classes 1, 51, 101, 151 and 201 corresponds to the NIKURADSE option of the WAQUA/TRI-
WAQ flow solver.

Method 2
DR

The total roughness is computed by first averaging over the serial and parallel averages of the
Chézy values according

Carea = αs Carea,s + (1 − αs )Carea,p (13.54)

where αs = 0.6 by default. Subsequenty the effect of the water free area fraction fb is
taken into account by means of the following empirical relation (identical to Equation (13.53)
of method 1).

fb = max(min(0.843, fb ), 0.014) (13.55)

 p 
Carea,corr =Carea 1.12 − 0.25fb − 0.99 fb (13.56)

Finally the Chézy value representing the total bed roughness is computed by accumulating
the inverses of the squared Chézy values.

1 1 1 1
2
= 2
+ 2
+ 2 (13.57)
Ctotal Carea,corr Clin Cpnt

The resulting Ctotal value is used in the computation. This method together with trachytope
classes 1, 51, 52, 53, 101, 152, 202 and 251 corresponds to the ROUGHCOMBINATION
option of the WAQUA/TRIWAQ flow solver.

13.3 Dynamic vegetation model

Deltares 214 of 562

 Bedforms and vegetation

13.3.1 Introduction
Next to the vegetation approaches in the previous sections of this chapter D-Flow FM also
offers the possibility of a dynamic vegetation model. Then, an ecological model that has
been developed in Python is coupled to D-Flow FM. By doing so a fast and flexible coupling
platform is created to answer questions about the design and evaluation of Nature-based
solutions (NbS), thereby enabling assessments that were considered too complicated and
costly before. The software used is open software.

13.3.2 Philosophies of dynamic vegetation model

T
Faced with the problems of climate change and socio-economic pressure in many of the
world’s deltas and rivers, there is a rising interest in Nature-based solutions as a means to
combine affordable and adaptive flood risk reduction with other ecosystem services. This has
created a demand for tools that can quantify the development and performance of natural or
AF nature-based systems like salt marshes, mangroves and river floodplains and the ecosystem
services they provide. The NbS Dynamics modelling suite provides the tools to simulate in-
teractions between hydrodynamics, sediment dynamics, morphodynamics and vegetation/e-
cology.

The ecological model can be as simple as a single habitat suitability rule, or endlessly com-
plex involving multiple species, age classes and stressors. To facilitate the assessment of
ecological processes, Delft3D Flexible Mesh has been expanded with summarizing statistics
of ecologically relevant parameters (e.g. inundation time, bed shear stress). The ecological
model is not restricted to vegetation only. Other biota that interact with hydrodynamics or
morphology, such as mussels, algae and microfytobenthos, can also be computed with this
DR

modelling suite.

A substantial improvement over the earlier academic tools is the direct exchange of param-
eters through memory pointers, instead of via files. This is much faster, allows for flexible
exchange intervals (i.e. only when really needed) and allows for relatively independent devel-
opment of both parts of the coupled code.

13.3.3 Conceptual description

The vegetation module in Python is coupled to a hydrodynamic D-Flow FM model. The Python
environment has two functions: it contains the vegetation module and it ‘orchestrates’ the
interaction between the hydrodynamic and the vegetation modules. ‘Orchestrating’ means
that Python is used to define when and via which parameters the models interact. To do so,
it uses the Basic Model Interface (BMI) technique (Hutton et al., 2020; Peckham et al., 2013).
The BMI interface of D-Flow FM is described in more detail in Section 17.1).

Deltares 215 of 562

 Bedforms and vegetation

T
AF Figure 13.1: Conceptual schematization of the modelling environment, visualizing the
Basic Model Interface connecting the D-Flow FM model for hydrodynamic
and morphodynamic computation with the Python environment for vegeta-
tion and ecological modelling

The modelling environment is illustrated by a conceptual schematization in Figure 13.1. The

hydrodynamic module D-Flow FM computes for example the water level, flow velocity and
bed shear stress and passes these results to the vegetation module (Python). The vegetation
DR

module then computes the vegetation biomass, expressed as a stem density, stem height and
stem diameter. These vegetation parameters are used as inputs for D-Flow FM in the next
timestep.

13.4 (Rigid) three-dimensional vegetation model

The (rigid) 3D Vegetation model (Winterwerp and Uittenbogaard (1997)), as known from
Delft3D-FLOW, is not available yet in D-Flow FM.

Deltares 216 of 562

14 Calibration factor for bed roughness
The current chapter explains the effect of the calibration factor. The calibration factor is mul-
tiplier of the roughness. The calibration factor may be constant, discharge- or water-level-
dependent. By assigning different areas to different calibration classes, each region can be
independently calibrated. Calibration roughness definitions can also be combined by assign-
ing multiple field definitions and a weighting for each gridcell edge (net link). This approach
allows thus both abrupt and gradual transitions and the modeller can control how the calibra-
tion factor is going to be used. The approach is similar to the roughness and link definitions
used in the trachytopes module for alluivial- and bedform-roughness (see chapter 13).

T
The calibration factor is defined by means of two files (see section C.9):
⋄ Calibration factor definition file (CLD-file). This file defines the calibration factor (e.g. con-
stant, water-level- or discharge dependent).
⋄ Calibration factor area file (CLL-file). This file associates calibration factor defintions with
AF the edges of the model grid and include a relative weighting.

The resulting weighted calibration factor is multiplied by the roughness type as expressed by
the UnifFrictCoef keyword in the [physics] section in the .mdu file (see Appendix A).
This implies that the effect of the calibration will be different depending on the definition of
UnifFrictCoef. For example, if the UnifFrictCoef=0 (i.e. Chézy) a local calibration
factor of 0.5 will imply an increase of the bed shear stress, whereas if UnifFrictCoef=2
(i.e. White-Colebrook) a reduction of the bed shear stress may be expected. A background
calibration factor equal to one is applied if the sum of the weights at a single link is lower than
one.
DR

The calibration factor approach cannot be combined with multiple roughness types as speci-
fied through the external forcing file. This will lead to an error. Such a spatial variation in the
roughness can be achieved by defining these areas through the trachytopes module.

It is good to be aware of the following known differences with the trachytopes module:
⋄ The weighting of the calibration factors is done for all entries in the calibration area defin-
tion file. Averaging for the trachytopes area file is only done for the last sequence of
trachytope area defintions at one and the same location.
⋄ When a calibration factor definition is imposed at a location outside of the grid, and this
calibration factor definition depends on a water level station or cross-section which is also
outside of the domain, the model crashes, however the trachytopes module allows this.

Deltares 217 of 562

15 Wind
Various external influences can exert a force on the flow field. One of these influences is the
wind. The force exerted by the wind is coupled to the flow equations as a shear stress. The
magnitude is determined by the following widely used quadratic expression:
2
|τ s | = ρa Cd U10 (15.1)

where:
ρa the density of air.

T
U10 the wind speed 10 meter above the free surface (time and space dependent).
Cd the wind drag coefficient, dependent on U10 .

In order to specify the wind shear stress, a drag coefficient is required as well as the wind
field in terms of velocity magnitude and wind direction. In this chapter, the backgrounds
AF are provided of how wind fields should be imposed, in addition to section 7.4.9.4. Relevant
definitions are addressed in section 15.1, whereas supported file formats are addressed in
section 15.2.

The density of air in the computation of the wind stress is considered constant as a default,
but it is also possible to use a time- and space-varying air density. The air density can be
prescribed directly as a timeseries field or it can be computed from prescribed time- and
space-varying air pressure, air temperature and dew point temperature (see section E.1.9).

The steps to compute the air density [kg m−3 ] are (following ECMWF (2023)):
DR

e = e0 exp(17.502(Td − T0 )/(Td − 32.19)) (15.2)

e
qv = ∗
(15.3)
p + ε (p − e)
Rv
ε∗ = −1 (15.4)
Rd
Tv = (1 + ε∗ qv )T (15.5)
p
ρa = (15.6)
Rd Tv
where
e water vapour saturation pressure [Pa].
e0 water vapour saturation pressure over water at T0 [611.21 Pa].
T0 triple point temperature [K].
Td dew point temperature [K].
qv specific humidity [g kg−1 ].
p atmospheric pressure [Pa].
Rv gas constant for water vapor [461.5249 J kg−1 K−1 ].
Rd gas constant for dry air [287.0596 J kg−1 K−1 ].
Tv virtual temperature [K].
T air temperature [K].

15.1 Definitions
When imposing wind conditions, two definitions are respected: a definition for the wind direc-
tion (see section 15.1.1) and a definition regarding the drag coefficient (see section 15.1.2).

Deltares 218 of 562

 Wind

15.1.1 Nautical convention

The wind direction is defined according to the nautical definition, i.e. relative to true North and
positive measured clockwise. In Figure 15.1 the wind direction is about +60 degrees, i.e. an
East-North-East wind.

T
AF
Figure 15.1: Nautical conventions for the wind.
DR

15.1.2 Drag coefficient

The user can select how the wind drag coefficient should be computed, by specifying the type
of wind drag formulation in the mdu-file. For this purpose, the keyword ICdtyp should be
used. Nine options are available:
⋄ ICdtyp = 1 – constant drag coefficient,
⋄ ICdtyp = 2 – linearly varying drag coefficient (cf. Smith and Banke (1975)),
⋄ ICdtyp = 3 – piecewise linearly varying drag coefficient (cf. Smith and Banke (1975)),
⋄ ICdtyp = 4 – Charnock (1955) formulation,
⋄ ICdtyp = 5 – Hwang (2005a) and Hwang (2005b) formulation,
⋄ ICdtyp = 6 – Wüest and Lorke (2003) formulation,
⋄ ICdtyp = 7 – Hersbach (2011) formulation,
⋄ ICdtyp = 8 – Charnock (1955) formulation plus viscous effect,
⋄ ICdtyp = 9 – Garratt (1977) formulation.

If one of the Smith & Banke type dependencies is selected, the additional entries Cdbreakpoints
and Windspeedbreakpoints come into play. In the following sections, these various op-
tions are described in more detail.

Deltares 219 of 562

 Wind

Smith & Banke type formulation

When specifying a Smith & Banke type dependency, the definition as sketched in Figure 15.2
should be kept in mind.

T
AF
Figure 15.2: Prescription of the dependency of the wind drag coefficient Cd on the wind
speed is achieved by means of at least 1 point, with a maximum of 3 points.

From this sketch, it can be seen that the wind drag is considered as dependent on the wind
speed in a piecewise linear way. The options, that are facilitated in this respect, are:
⋄ define one set of coordinates (breakpoint A), specifying a constant drag coefficient, valid
DR

for all wind speeds,

⋄ define two sets of coordinates (breakpoints A and B), specifying a linearly varying depen-
dency for one range of wind speeds,
⋄ define three sets of coordinates (breakpoints A, B and C), specifying a piecewise linear
dependency for two ranges of wind speeds.

Remark that for the latter two options, the drag coefficient is taken constant for wind speeds
lower/higher than the lowest/highest specified wind speed, with a drag coefficient equal to the
drag coefficient associated with the lowest/highest specified lowest/highest wind speed. In
case of three breakpoints, the expression reads:
 A A

 Cd , U10 ≤ U10 ,
A
C A + C B − C A U10 − U10 ,


A B
U10 ≤ U10 ≤ U10 ,

d d d B A
− U10

Cd (U10 ) = U10 (15.7)
B
B C B U10 − U10

B C
C + C − C , U10 ≤ U10 ≤ U10 ,


d d d C B
− U10



 U10
 C C
Cd , U10 ≤ U10 ,
By means of the entries Cdbreakpoints and Windspeedbreakpoints, the coor-
dinates of the breakpoints (see Figure 15.2) can be specified. Typical values associated
with the Smith and Banke (1975) formulation are Cd = 6.3 × 10−4 for U = 0 m/s and
Cd = 7.23 × 10−3 for U = 100 m/s. In this case, the entries in the mdu-file should be
specified as follows:

[wind]
ICdtyp = 2

Deltares 220 of 562

 Wind

Cdbreakpoints = 0.00063 0.00723

Windspeedbreakpoints = 0.00000 100.00000

Relative wind
In D-Flow FM, there is the possibility to compute wind shear stress based on the relative wind
velocity, i.e. relative to the flow velocity. This becomes important when the flow is predomi-
nantly forced by the wind and the flow velocity is in the order of the wind velocity. In this way,
one can avoid that the wind still forces the flow, despite a zero (or small) difference between
flow and wind speed. In case of relative wind Equation (15.1) is changed to

T
|τ s | = ρa Cd (U10 − αUflow )2 (15.8)

where:
AF
ρa
U10
Cd
the density of air.
the wind speed 10 meter above the free surface (time and space dependent).
the wind drag coefficient, dependent on U10 .
Uflow the flow velocity.
α the relative wind factor.

This option can be switched on via keyword Relativewind. Then, a value between 0 and
1 has to be specified, which acts as a factor for relative wind, as shown in Equation (15.8).

Charnock formulation
DR

The Charnock formulation (see Charnock (1955)) is based on the assumption of a fully devel-
oped turbulent boundary layer of the wind flow over the water surface. The associated wind
speed profile follows a logithmic shape. In the Charnock formulation, the wind speed is con-
sidered at 10 meters above the free water surface, hence yielding the following expression:

 
U10 1 z10
= ln (15.9)
u∗ κ z0
with κ the Von Kármán constant, z10 the distance to the water surface (equal to 10 m), u∗ the
friction velocity and U10 the wind speed at 10 m above the water surface. The drag coefficient
Cd is defined as:
u2∗
Cd = 2
. (15.10)
U10
Charnock (1955) has proposed to represent the friction of the water surface as z0 according
to:

b u2∗
z0 = , (15.11)
g
with g the gravitation acceleration and b a specific constant. Charnock (1955) has proposed
b = 0.012. The value of the constant b can be specified in the mdu-file by the user by means
of one single value for Cdbreakpoints. Since the above relation yields an implicit relation
for u∗ , the system is solved for iteratively. The user should be aware of interpretation of the
specified wind field as the wind field at 10 m above the water surface. See section 15.2.4 for
a space and time varying Charnock coefficient b.

Deltares 221 of 562

 Wind

Hwang formulation
The dynamic roughness could also be related to the steady state wave conditions of the flow
field under consideration. The connection of the wave parameters with the drag coefficient as
elaborated by Hwang (2005a) is available within D-Flow FM through ICdtyp = 5, given a
wave field. The Hwang-formulation interprets the user defined wind speed as the wind speed
at 10 m above the water surface.

The drag coefficient is computed as:

  −2
1 kp z10

T
Cd = ln (15.12)
κ kp z0
with z10 = 10 m, κ the Von Kármán constant. With wavelength scaling, kp z0 is the natural
expression of the dimensionless roughness, where kp is the wave number of the spectral
peak, computed on the basis of the actual water depth and the provided peak period Tp as
AF
wave field. Further following Hwang (2005a),

−0.5

kp z0 = π exp −κCλ/2 (15.13)

in which Cλ/2 is the drag coefficient at half the wavelength above surface. This parameter
Cλ/2 is computed as:
 a10
ωp U10
Cλ/2 = A10 (15.14)
g
DR

in which A10 = 1.289 × 10−3 , a10 = 0.815, U10 the wind speed at 10 m above the water
surface and ωp the wave peak frequency (ωp = 2π/Tp ). Thus, the drag coefficient Cd is
defined.

Wuest formulation
Wüest and Lorke (2003) define the drag coefficient as
(
0.00063 + 0.000066U10 if U10 > 4
Cd = −1.15
(15.15)
0.0044 max(0.1, U10 ) if U10 ≤ 4

Hersbach formulation
Hersbach (2011) defines the drag coefficient as
 2
κ
Cd = (15.16)
bfitn
ν α
where bfit
n is split into a viscous bn and Charnock bn contribution as

bfitn = [(bνn )p + (bαn )p ]1/p (15.17)

bνn = −1.47 + 0.93 ln R (15.18)
bαn = 2.65 − 1.44 ln A − 0.015(ln A)2 (15.19)

in which
αch
A= (κU10 )2 (15.20)
gz10

Deltares 222 of 562

 Wind

and
z10
R= κU10 (15.21)
αM νair
where z10 equals the elevation at which the velocity is given, i.e. 10 m. The values of the
constants αch and αM can be specified in the mdu-file by the user by means of two values
for Cdbreakpoints.

Charnock with viscous

T
When this option is selected, the drag coefficient is computed according Equation (15.10)
where u∗ is determined iteratively using

b1 u2∗ b2 νair
z0 = + (15.22)
g u∗
AF and Equation (15.9). The values of the constants b1 and b2 can be specified in the mdu-file
by the user by means of two values for Cdbreakpoints.

Garratt formulation
Garratt (1977) defines the drag coefficient as

Cd = min(10−3 (0.75 + 0.067U10 ), 0.0035) (15.23)

This formulation can also be represented as a Smith & Banke type formulation.
DR

[wind]
ICdtyp = 2
Cdbreakpoints = 0.00075 0.0035
Windspeedbreakpoints = 0.00000 41.0448

15.2 File formats

The wind field should be provided by means of meteo forcing file(s). Most commonly used
types are various ASCII-formatted files and NetCDF. Section C.6.2.3 lists all supported for-
mats. This file should contain the grid on which the wind field is defined as well as the wind
velocity vector(s).

D-Flow FM currently supports four types of wind field prescriptions, i.e. four grid types on
which the wind field can be given. This wind grid does not need to be the same as the
computational grid. The grid options to provide the wind data on are:
1 the computational grid — in this case, no specific wind grid is provided. The provided wind
field is considered to be uniform over the entire model area. The wind field can be time
dependent.
2 an equidistant grid — in this case, a wind field can be prescribed that varies both in space
and in time. A Cartesian ArcInfo-type file or NetCDF file should be provided on which the
wind field is defined.
3 a curvilinear grid — this case is conceptually similar to the previous type (the equidistant
grid) in the sense that a wind field can be imposed that both varies in space and time.
However, for ArcInfo-type data files, a separate file should be provided in which a curvilin-
ear grid is defined (a classic <∗.grd>-type file as known from Delft3D-FLOW) on which
the wind field is defined. For NetCDF this is not necessary: all meteo grid coordinates
must be present in the same NetCDF file that contains the meteo forcing data itself.

Deltares 223 of 562

 Wind

4 a spiderweb grid — this type of wind specification is specially devoted to cyclone winds
and is only available in combination with computational grids that are of spherical type.
In this case, a cyclone wind field is given on a polar grid with the center (’eye’) of the
cyclone being the origin of the polar coordinate system. The location of this eye and the
associated wind field usually varies in time.

Each of these filetypes can be assigned through the entry in the new external forcings file (the
<∗.ext>-file) named forcingFileType.

T
Warning:
⋄ Deprecated: In the old <*.ext> file, the keyword was called FILETYPE. Now, the new
external forcings file is the only place when meteo must be specified.

In this chapter, the various types of wind field specifications are highlighted subsequently.
Each of the options is illustrated by means of an example.
AF
15.2.1 Defined on the computational grid
In D-Flow FM, the specification of the wind on the computational grid is comparable to the
specification of a spatially uniform wind, since no separate wind grid is provided to the model.
The specification of a uniform wind field can be done in two ways:
1 componentwise: as velocity in the longitudinal x-direction [m/s] and in the latitudal y -
direction [m/s] — with forcingFileType=bcAscii (Deprecated: formerly this was
via FILETYPE=1 and a <*.tim> file in the old <*.ext> file).
2 by magnitude [m/s] and direction [degN] (see Figure 15.1) — with forcingFileType
DR

= uniMagDir (Deprecated: formerly this was FILETYPE=2 in the old <*.ext> file).

These two types are treated below separately.

15.2.1.1 Specification of uniform wind through velocity components

Since no particular wind grid is used, only timeseries for the x-component and the y -compo-
nent of the wind need to be specified. The specification of these timeseries can be done
separately (one single file for the x-component and one single file for the y -component) or
jointly (one single file containing the x-component and the y -component of the wind).

Uniform wind should be provided as a <*.bc> file.

Warning:
⋄ Deprecated: formerly, this was via a <*.wnd>-file containing either 2 colums (in case of
separate specification of the x-component and y -component of the wind) or 3 columns
(in case of joint specification of the velocity components). In either case, the first column
contains the time in minutes with respect to the overall reference time.

Example
As an example, a uniform wind field is applied to a certain model. The uniform wind is provided
in a <*.bc> file named windxdirydir.bc. The contents of this wind file are:

[Forcing]
Name = global
Function = timeSeries
Time-interpolation = linear

Deltares 224 of 562

 Wind

Vector = windxy:wx,wy
Quantity = time
Unit = minutes since 2006-01-01 0:00:00
Quantity = wx
Unit = ms-1
Quantity = wy
Unit = ms-1
0.00000 10.00000 10.00000
60.00000 -10.00000 -10.00000

Warning:

T
⋄ Deprecated: The old external forcing file is being deprecated, as well as timeseries files
<*.tim> and <*.wnd>. The example below is kept only for migration purposes:

Before, the uniform wind could also be provided in a <*.wnd> file named windxdirydir.wnd.
The contents of this wind file are:
AF0.00000
60.00000
10.00000
-10.00000
10.00000
-10.00000

The first column denotes the time in minutes with respect to the reference date (specified in
the mdu-file). The second column denotes the wind velocity in x-direction, whereas the third
column denotes the wind velocity in y -direction; both wind components are provided in one
single file.
DR

The connection with the flow model itself is laid through the external forcings file. The actual
specification of the wind is in this case:

[Meteo]
quantity = windxy
forcingFileName = windxdirydir.bc
forcingFileType = bcAscii
interpolationMethod = linearSpaceTime
operand = O

Warning:
⋄ Deprecated: The old external forcing file is being deprecated. The example below is
kept only for migration purposes:

QUANTITY =windxy
FILENAME =windxdirydir.wnd
FILETYPE =1
METHOD =1
OPERAND =O

Since the two components are given in one single file, the QUANTITY is set to windxy. If
two separate files would have been provided, the QUANTITY would have been set to windx
and windy over two separate datablocks in the external forcings file.

Deltares 225 of 562

 Wind

15.2.1.2 Specification of uniform wind through magnitude and direction

Instead of specifying the separate components of the wind field, the uniform wind vector can
also be prescribed through its magnitude and direction (see Figure 15.1).

This kind of specification should be done by means of one single file, containing three columns,
representing the time (in minutes with respect to the reference date), the velocity magnitude
[m/s], not necessarily positive, and the direction (nautical convention).

Example

T
As an example, the previous uniform wind case is reformulated as a case with magnitude
and direction of the wind field prescribed. The unimagdir wind is provided in a file named
AF <windinput.wnd>. The contents of this file are:

0.00000 14.14213562373095 225.00000

60.00000 -14.14213562373095 225.00000

The first column denotes the time in minutes with respect to the reference date (specified in
the mdu-file). The second column denotes the wind velocity magnitude, whereas the third
column denotes the wind direction. Note that there is a clear difference between the above
case and a case in which the magnitude is kept positive (14.1421 m/s) and the direction varies
(and hence rotates!) from 225 degN to 45 degN.

The connection with the flow model itself is laid through the external forcings file. The actual
DR

specification of the wind is in this case:

[Meteo]
quantity = windxy
forcingFileName = windinput.wnd
forcingFileType = uniMagDir
interpolationMethod = linearSpaceTime
operand = O

Warning:
⋄ Deprecated: The old external forcing file is being deprecated. The example below is
kept only for migration purposes:

QUANTITY =windxy
FILENAME =windinput.wnd
FILETYPE =2
METHOD =1
OPERAND =O

15.2.2 Defined on an equidistant grid

The vector components of the velocity vectors can also be specified on a distinct grid, either of
equidistant type or of curvilinear type. In both cases, the characteristics of the grid should be
provided. In case of an equidistant grid, the grid is specified in arcinfo-style. That means, the
constant grid sizes ∆x and ∆y should be specified such that a grid is spanned with respect
to the location of the lower left corner of the grid (either the center of the lower left cell or the
lower left corner of the lower left cell).

Deltares 226 of 562

 Wind

Example
As an example, a grid with ∆x = ∆y = 100 m is spanned, based on the center of the
lower left cell, located at x = y = 60 m with respect to the origin. The input data for the x-
component and the y -component should be specified separately, in two distinct files. The input
of the x-component data should be given in an <∗.amu>-type file, such as <windxdir.amu>
as an example:

### START OF HEADER

### This file is created by Deltares

T
### Additional commments
FileVersion = 1.03
filetype = meteo_on_equidistant_grid
NODATA_value = -9999.0
n_cols = 5
n_rows = 4
grid_unit = m
AF
x_llcenter
y_llcenter
dx
dy
n_quantity
=
=
=
=
=
60
60
110
110
1
quantity1 = x_wind
unit1 = m s-1
### END OF HEADER
TIME = 0 hours since 2006-01-01 00:00:00 +00:00
10 10 10 10 10
10 10 10 10 10
10 10 10 10 10
10 10 10 10 10
TIME = 1 hours since 2006-01-01 00:00:00 +00:00
-10 -10 -10 -10 -10
DR

-10 -10 -10 -10 -10

-10 -10 -10 -10 -10
-10 -10 -10 -10 -10

For the y -component data, a similar file (e.g. <windydir.amv>) should be provided. In ad-
dition, the pressure could be specified in a similar file (e.g. <pressure.amp>). Note that
x_llcorner and y_llcorner, instead of x_llcenter and y_llcenter, are also
supported.

Wind on an equidistant grid has been provided a filetype specification as forcingFileType=ArcInfo.

The connection with the flow model itself is laid through the external forcings file. The actual
specification of the wind is in this case:

[Meteo]
quantity = windx
forcingFileName = windxdir.amu
forcingFileType = ArcInfo
interpolationMethod = linearSpaceTime
operand = O

[Meteo]
quantity = windy
forcingFileName = windydir.amv
forcingFileType = ArcInfo
interpolationMethod = linearSpaceTime
operand = O

[Meteo]
quantity = atmosphericpressure
forcingFileName = pressure.amp
forcingFileType = ArcInfo
interpolationMethod = linearSpaceTime
operand = O

Deltares 227 of 562

 Wind

Warning:
⋄ Deprecated: The old external forcing file is being deprecated. The example below is
kept only for migration purposes:

QUANTITY =windx
FILENAME =windxdir.amu
FILETYPE =4
METHOD =2
OPERAND =O

QUANTITY =windy

T
FILENAME =windydir.amv
FILETYPE =4
METHOD =2
OPERAND =O

QUANTITY =atmosphericpressure
FILENAME =pressure.amp
FILETYPE =4
AF METHOD
OPERAND
=2
=O

15.2.3 Defined on a curvilinear grid

In analogy with the wind specification on an equidistant grid, the wind can be specified on a
curvilinear grid. This curvilinear grid should be provided as a classic <∗.grd>-file as known
from Delft3D-FLOW. A difference with the equidistant grid wind is the necessity to compile all
data blocks (i.e. pressure, x-component and y -component) in one single file. This file should
have the extension <∗.apwxwy>. The sequence of this datablock is:
DR

1 pressure,
2 x-velocity component,
3 y -velocity component.

Example
As an example, a curvilinear grid named <meteo.grd> is present, providing the underlying
coordinates of the wind data field. The input data, comprising the atmospheric pressure,
the x-velocity component and the y -velocity component, are given in one single file (as is
compulsory). The contents of the example <meteo.apwxwy>-file is:

### START OF HEADER

### This file is created by Deltares
### Additional commments
FileVersion = 1.03
filetype = meteo_on_curvilinear_grid
NODATA_value = -9999.0
grid_file = meteo.grd
first_data_value = grid_llcorner
data_row = grid_row
n_quantity = 3
quantity1 = air_pressure
unit1 = Pa
quantity2 = x_wind
unit2 = m s-1
quantity3 = y_wind
unit3 = m s-1
### END OF HEADER
TIME = 0.0 hours since 2006-01-01 00:00:00 +00:00
101325 101325 101325 101325 101325
101325 101325 101325 101325 101325
101325 101325 101325 101325 101325
101325 101325 101325 101325 101325
10 10 10 10 10

Deltares 228 of 562

 Wind

10 10 10 10 10
10 10 10 10 10
10 10 10 10 10
10 10 10 10 10
10 10 10 10 10
10 10 10 10 10
10 10 10 10 10
TIME = 1.0 hours since 2006-01-01 00:00:00 +00:00
101325 101325 101325 101325 101325
101325 101325 101325 101325 101325
101325 101325 101325 101325 101325
101325 101325 101325 101325 101325
-10 -10 -10 -10 -10
-10 -10 -10 -10 -10

T
-10 -10 -10 -10 -10
-10 -10 -10 -10 -10
-10 -10 -10 -10 -10
-10 -10 -10 -10 -10
-10 -10 -10 -10 -10
-10 -10 -10 -10 -10
AF Note that grid_llcenter, instead of grid_llcorner, is also supported. On the con-
trary, grid_column is not supported instead of grid_row.

Wind on a curvilinear grid has been provided a filetype specification as FILETYPE=6. The
connection with the flow model itself is laid through the external forcings file. The actual
specification of the wind is in this case:

QUANTITY =airpressure_windx_windy
FILENAME =meteo.apwxwy
DR

FILETYPE =6
METHOD =3
OPERAND =O

Notice that METHOD=3 is chosen for wind on a curvilinear grid, instead of METHOD=2 in case
of wind on an equidistant grid.

15.2.4 Space and time varying Charnock coefficients

The value for the Charnock coefficient b in Equation (15.11) can be a constant given in the
mdu-file, but also be given as a space and time varying field.

For a space and time varying Charnock coefficient, the user should provide a netCDF-file
with meteorological forcing, including Charnock coefficients, and use the file specification
forcingFileFormat=netcdf.

The specification is in this case in the new <*.ext> file:

[Meteo]
quantity = airpressure_windx_windy_charnock
forcingFileName = meteo.nc
forcingFileType = netcdf
interpolationMethod = linearSpaceTime
operand = O

Warning:

Deltares 229 of 562

 Wind

⋄ Deprecated: The old external forcing file is being deprecated. The example below is
kept only for migration purposes:

QUANTITY =airpressure_windx_windy_charnock
FILENAME =meteo.nc
FILETYPE =11
METHOD =3
OPERAND =O

T
15.2.5 Rainfall
Rainfall can be defined as rainfall and rainfall_rate. The difference is: rainfall
is the cumulative precipitation [mm] (for each point in the timeseries measured since the
previous point in that timeseries) and rainfall_rate is the instantaneous precipitation
[mm/day].
AF The specification is in the new <*.ext> file:

[Meteo]
quantity = rainfall_rate
forcingFileName = rad_nl25_rac_mfbs_5min.nc
forcingFileType = netcdf
forcingVariableName = image1_image_data
interpolationMethod = linearSpaceTime
operand = O
DR

Warning:
⋄ Deprecated: The old external forcing file is being deprecated. The example below is
kept only for migration purposes:

QUANTITY=rainfall_rate
FILENAME=rad_nl25_rac_mfbs_5min.nc
VARNAME =image1_image_data
FILETYPE=11
METHOD=3
OPERAND=O

The unit of rainfall is [mm/day]. So, this is the case for rainfall input either via a <*.bc> file or
a netCDF-file.

15.2.6 Defined on a spiderweb grid

Cyclone winds can be imposed by means of a ’spiderweb’-like polar grid. The origin typi-
cally coincides with the cyclone eye and can move in time. Spiderwebs can only be used in
combination with a spherical computational grid. The origin of the spiderweb should be given
as longitude (for xeye ) and latitude (for yeye ). The number of rows (discretisation in radial
direction) and the number of columns (discretisation in angular direction) should be given, as
well as the radius of the grid (in meters). The definition of the spiderweb grid is illustrated in
Figure 15.3.

Deltares 230 of 562

 Wind

T
AF
Figure 15.3: Grid definition of the spiderweb grid for cyclone winds.
DR

The files containing the spiderweb data and metadata have the extension <∗.spw>. They
consist of a global header containing properties that are not varying in time, followed by blocks
of data for subsequent time levels. Each of these data blocks is headed by a set of properties
for the corresponding time level. A detailed description of the spiderweb file format can be
found in section C.13.3.

Through the specified unit for atmospheric pressure in the file, it can be specified whether the
values should be interpreted as mbar (=hPa), instead of Pa, which is the default. Specifying
the spiderweb merge fraction β in spw_merge_frac allows for linear fading of wind speed
and pressure drop towards the outer rim. For a spiderweb with radius R, the weigth assigned
to the spiderweb wind and pressure at a radius r is given by (R − r)/βR for r between
(1 − β)R and R. The weight equals unity within the inner circle and zero beyond the outer
rim.

Example
As an example, a spiderweb grid named <spwsimple.spw> is present, providing the under-
lying coordinates of the wind data field. The input data, comprising the atmospheric pressure
drops, the wind velocity magnitudes (in [m/s]) and the wind directions (in [degN]), are given in
one single file (as is compulsory). The contents of the example <spwsimple.spw>-file is:

### Spiders web derived from TRACK file: gonu.trk

### This file is created by Deltares
### All text on a line behind the first # is parsed as commentary
### Additional commments
FileVersion = 1.03
filetype = meteo_on_spiderweb_grid
### Spiders web derived from TRACK file: gonu.trk
### This file is created by Deltares
### All text on a line behind the first # is parsed as commentary

Deltares 231 of 562

 Wind

### Additional commments

NODATA_value = -1001
n_cols = 4
n_rows = 4
spw_radius = 600000.0
spw_merge_frac = 0.75
spw_rad_unit = m
### END OF HEADER
TIME = 340000.00 minutes since 2005-01-01 00:00:00 +00:00
x_spw_eye = 265.00
y_spw_eye = 33.00
p_drop_spw_eye = 7000.000
5.000000 5.000000 5.000000 5.000000
10.000000 10.000000 10.000000 10.000000

T
15.000000 15.000000 15.000000 15.000000
20.000000 20.000000 20.000000 20.000000
270.00 0.00 90.00 180.00
270.00 0.00 90.00 180.00
270.00 0.00 90.00 180.00
270.00 0.00 90.00 180.00
4000.00 4000.00 4000.00 4000.00
AF
3000.00
2000.00
1000.00
TIME
x_spw_eye
3000.00
2000.00
1000.00
3000.00
2000.00
1000.00
= 380000.00
= 275.00
3000.00
2000.00
1000.00
minutes since 2005-01-01 00:00:00 +00:00

y_spw_eye = 18.00
p_drop_spw_eye = 8000.000
5.000000 5.000000 5.000000 5.000000
10.000000 10.000000 10.000000 10.000000
15.000000 15.000000 15.000000 15.000000
20.000000 20.000000 20.000000 20.000000
270.00 0.00 90.00 180.00
270.00 0.00 90.00 180.00
270.00 0.00 90.00 180.00
270.00 0.00 90.00 180.00
DR

4000.00 4000.00 4000.00 4000.00

3000.00 3000.00 3000.00 3000.00
2000.00 2000.00 2000.00 2000.00
1000.00 1000.00 1000.00 1000.00

Wind on a spiderweb grid has been provided a filetype specification as FILETYPE=5. The
connection with the flow model itself is laid through the external forcings file. The actual
specification of the wind in the new <*.ext> file:

[Meteo]
quantity = airpressure_windx_windy
forcingFileName = spwsimple.spw
forcingFileType = spiderWeb
interpolationMethod = linearSpaceTime
operand = O

Warning:
⋄ Deprecated: The old external forcing file is being deprecated. The examples below are
kept only for migration purposes:

QUANTITY =airpressure_windx_windy
FILENAME =spwsimple.spw
FILETYPE =5
METHOD =1
OPERAND =O

Notice that METHOD=1 is chosen for wind on a spiderweb grid, instead of METHOD=2 in case
of wind on an equidistant grid and METHOD=3 in case of wind on a curvilinear grid.

Deltares 232 of 562

 Wind

Alternatively, the spiderweb wind and pressure can be specified in the external forcings file as
separate quantities referring to the same file (or specify one and omit the other):

QUANTITY =windxy
FILENAME =spwsimple.spw
FILETYPE =5
METHOD =1
OPERAND =O

QUANTITY =airpressure
FILENAME =spwsimple.spw

T
FILETYPE =5
METHOD =1
OPERAND =O

(NB. There is a slight difference between both specifications regarding their effect on the flow.
AF The first approach requires an additional interpolation of wind on the velocity points, which in
some cases of coarse computational grids and small scale wind could introduce smoothing.)

15.2.7 Combination of several wind specifications

The combination of the various wind specification types can only be achieved if the quantity
of the winds to be combined is the same, for instance quantity=windx. The option
operand=+ can be used to add a wind field to an existing wind field.

Example
DR

If the uniform wind is to be combined with a wind specified on an equidistant grid, then the
wind field could be assigned in the new external forcings file as follows:

[Meteo]
quantity = windx
forcingFileName = windxdir.bc
forcingFileType = bcAscii
interpolationMethod = linearSpaceTime
operand = O

[Meteo]
quantity = windy
forcingFileName = windydir.bc
forcingFileType = bcAscii
interpolationMethod = linearSpaceTime
operand = O

[Meteo]
quantity = windx
forcingFileName = windxdir.amu
forcingFileType = ArcInfo
interpolationMethod = linearSpaceTime
operand = +

[Meteo]
quantity = windy
forcingFileName = windydir.amv
forcingFileType = ArcInfo
interpolationMethod = linearSpaceTime
operand = +

Warning:
⋄ Deprecated: The old external forcing file is being deprecated. The examples below are
kept only for migration purposes:

Deltares 233 of 562

 Wind

QUANTITY =windx
FILENAME =windxdir.wnd
FILETYPE =1
METHOD =1
OPERAND =O

QUANTITY =windy
FILENAME =windydir.wnd
FILETYPE =1
METHOD =1
OPERAND =O

T
QUANTITY =windx
FILENAME =windxdir.amu
FILETYPE =4
METHOD =2
OPERAND =+

QUANTITY =windy
FILENAME =windydir.amv
AF
FILETYPE
METHOD
OPERAND
=4
=2
=+

The same is possible for e.g. a uniform wind and two spiderweb cyclones:

QUANTITY=windxy
FILENAME=uni.tim
FILETYPE=2
METHOD=1
DR

OPERAND=O

QUANTITY =windxy
FILENAME =spwsimple.spw
FILETYPE =5
METHOD =1
OPERAND =+

QUANTITY =windxy
FILENAME =spwsimple2.spw
FILETYPE =5
METHOD =1
OPERAND =+

QUANTITY =atmosphericpressure
FILENAME =spwsimple.spw
FILETYPE =5
METHOD =1
OPERAND =+

QUANTITY =atmosphericpressure
FILENAME =spwsimple2.spw
FILETYPE =5
METHOD =1
OPERAND =+

In the above example, the wind is first prescribed as a spatially uniform time-varying field,
onto which the spiderweb winds are added Note that the uniform wind has the ’O’ operand,
which means that it overrides rather than adds. However, since the default wind is zero, one
might just as well have used the ’+’ operand. If the spiderweb merge fraction is specified
in the spiderweb file, a gradual transition between the spiderweb wind and the background
wind is applied using the linearly varying weight as described above. The same is done for
atmospheric pressure, if specified except that pressure is added to, whereas wind is averaged
with the background values. Without any input, the background atmospheric pressure is set
to PavBnd in the section [wind] in the mdu-file, if present and zero otherwise.

Deltares 234 of 562

 Wind

15.3 Masking of points in the wind grid from interpolation (‘land-sea mask’)
Warning:
⋄ Deprecated: The old external forcing file is being deprecated. Similar (but not equiv-
alent) functionality is available via the targetMaskFile keyword. More details are
listed in Section C.6.2.3.

A mask can be supplied by the user to prevent selected points in the wind grid from contribut-
ing to the wind interpolation on velocity points, e.g. to exclude land points. This feature was
included to conform to SIMONA and therefore implemented in the same way.

T
For each individual grid point for which to interpolate from the wind grid:
⋄ Masked wind points are excluded from the interpolation.
⋄ The total of the weight factors for the remaining wind points is determined.
⋄ If this total falls below 1E-03, the mask is ignored and the original bilinear weights are
AF used.
⋄ Otherwise, the weights for the remaining wind points are normalised again.

The effect of the mask, when applied as a land-sea mask, is that for velocity points close
to shore the interpolated wind is no longer influenced by the wind over land (which would
otherwise yield a zone of points with reduced wind near the shore).

Specification and format of the mask file

The name of the mask file, if any, is specified in the <.ext> file, labelled SOURCEMASK,
DR

directly following the FILENAME specification, e.g.:

QUANTITY =windxy
FILENAME =meteo.wxwy
SOURCEMASK =meteo_mask.asc
FILETYPE =6
METHOD =3
OPERAND =O

The mask file itself has the same layout as the wind file, though the number of required header
fields is reduced, e.g.:

FileVersion = 1.03
.
.

unit1 = Pa
### END OF HEADER
1 1 1 1 1
1 1 1 0 0
1 1 1 0 0
1 1 0 0 0

The lines in the header are ignored. The number of columns and rows in the matrix of ones
and zeros should match those of a block (for a single variable and a single timestep) in the
meteo files. Zeros signify the position of rejected points (and ones those of the accepted
points) in the wind grid.

Deltares 235 of 562

 16 Ice modelling in D-Flow FM
The ice functionality of D-Flow FM is currently limited to a non-moving ice cover. The ice cover
may either be externally specified or dynamically computed based on the thermodynamics of
the system. Frazil ice is not yet included.

The presence of an ice cover may influence

⋄ Wind shear, see section 16.3
⋄ Thermal exchange between water and atmosphere, see section 16.2.2
⋄

T
Precipitation and evaporation, see section 16.6
⋄ Wave growth and propagation, see section 16.7
⋄ Water pressure, see section 16.4
AF ⋄ Surface resistance, see section 16.5

16.1 Forced ice cover

In the case of a forced ice cover, the ice thickness hi (x, y, t) and the ice cover fraction
Ai (x, y, t) must be specified by the user via the external forcings file. A snow layer is not yet
supported in the forced ice cover mode. These two quantities may be specified via
⋄ ASCII equidistant grid
⋄ ASCII curvilinear grid
⋄ NetCDF curvilinear grid

The quantity names for hi and Ai are sea_ice_thickness and sea_ice_area_fraction,

DR

respectively.

16.2 Dynamic ice cover

The dynamic ice module consists of a thermodynamic model based on a single ice layer con-
cept with snow on top (Semtner Jr., 1976). The ice model keeps track of three spatial quan-
tities, namely the ice thickness hi (x, y, t), the snow thickness hs (x, y, t) and the ice cover
fraction Ai (x, y, t). Snowfall is prescribed via the precipitation input. In case of precipitation
and air temperatures below zero, then this is considered as snowfall; see also section 16.6.
Decay of the snow thickness is computed by the thermodynamic model.

16.2.1 Conservation laws

Although the current version does not yet include horizontal transport, it is foreseen that the
functionality will be extended to include horizontal transport of the ice cover based on the
elastic-viscous-plastic (EVP) sea-ice rheology of Hunke and Dukowicz (1997). Hence, the
equations below include the ice velocity components ui (x, y, t) and vi (x, y, t). The equa-
tions for the conservation of the mass of ice and snow are given by

∂(Ai hi ) ∂(ui Ai hi ) ∂(vi Ai hi )

+ + = Sice + Dice (16.1)
∂t ∂x ∂y
∂(Ai hs ) ∂(ui Ai hs ) ∂(vi Ai hs )
+ + = Ssnow + Dsnow + Qsnow (16.2)
∂t ∂x ∂y
In these equations, the right-hand side contains thermodynamic terms S∗ and diffusion terms
D∗ , with ∗ depending on the ice equation to be solved. The snowfall is represented by Qsnow .

Deltares 236 of 562

 Ice modelling in D-Flow FM

The equation for ice cover fraction Ai reads

∂Ai ∂(ui Ai ) ∂(vi Ai )

+ + = SA + DA (16.3)
∂t ∂x ∂y
with 0 ≤ Ai ≤ 1. The ice cover fraction or concentration represents the fraction of a
computational cell that is covered by ice. Due to horizontal transport of the ice cover (from ice
floes to icebergs), it is possible that only a part of a computational cell is covered by ice (and
snow). The ice velocities ui and vi are computed via the momentum equations
 
∂ui ∂(ui ui ) ∂(vi ui ) ∂ζ
+ τax + τwx + F x

T
M + + − f vi = M g (16.4)
∂t ∂x ∂y ∂x
 
∂vi ∂(ui vi ) ∂(vi vi ) ∂ζ
M + + + f ui = M g + τay + τwy + F y (16.5)
∂t ∂x ∂y ∂y
with ζ the water elevation, f the Coriolis force and M the ice mass, g the acceleration due
AF to gravity, F the internal stresses according to Hibler III (1979) and τa the air and τw the
water stresses, respectively. The internal ice stress F includes a compressive ice strength
according to

P = p∗ hi e−C(1−Ai ) (16.6)

with p∗ and C empirical constants of 2.5 × 104 and 20, respectively.

However, without horizontal movement, the ice velocity components ui (x, y, t) and vi (x, y, t)
are currently always zero and the ice fraction Ai is always equal to zero (no ice in a computa-
tional cell) or one (computational cell completely filled with ice). The Equations 16.1 and 16.2
DR

simplify to
∂hi
= Sice (16.7)
∂t
∂hs
= Ssnow + Qsnow (16.8)
∂t

16.2.2 Thermodynamics of the ice/snow cover

The vertical growth rate (or decay) of ice thickness is determined by the ice thermodynam-
ics. The model’s thermodynamic interactions between snow, ice, water, and atmosphere are
shown in the left panel of Figure 16.1. The heat fluxes through the ice are based on a simple
one layer ice model with snow on top, according to Semtner Jr. (1976). The right panel in
Figure 16.1 represents the (standard) temperature model in D-Flow FM when ice is absent.

Figure 16.1: Conceptual diagram of the ice-growth (left) and temperature (right) model

Deltares 237 of 562

 Ice modelling in D-Flow FM

The total heat flux through the free surface reads

Qtot = Qsn + Qan − Qbr − Qev − Qco (16.9)

with Qsn the net incident solar radiation (short wave), Qan the net incident atmospheric ra-
diation (long wave), Qbr the back radiation (long wave), Qev the evaporative heat flux (latent
heat) and Qco the convective heat flux (sensible heat). The subscript n refers to a net contri-
bution. Each of the heat fluxes in Equation (16.9) are described in detail in (Deltares, 2025c,
chapter 5). Furthermore, the net atmospheric radiation Qan and the back radiation Qbr have
been combined into the effective back radiation Qebr according to

T
Qebr = Qbr − Qan (16.10)

The effective back radiation Qebr reads

Qebr = αTs4 (16.11)

AF √
with α = εσ(0.39 − 0.05 ea )(1.0 − 0.6Fc2 ) in J m−2 s−1 K−4 , in which ea is the vapour
pressure, Fc the cloudiness factor, ε the emissivity factor of the atmosphere and the air and
σ the Stefan-Boltzman constant. In the numerical sea-ice model the temperature is assumed
to vary linearly between the top and bottom of the ice layer. By further assuming a constant
thermal conductive coefficient ki for ice, the heat conduction through the ice is given by

Ta − Tf
Qtot = −ki (16.12)
hi
which can be rewritten to
DR

Ta − Tf
Qtot without ebr − Qebr = −ki (16.13)
hi
in which the heat flux term Qtot without ebr no longer contains the effective back radiation flux and
in which Tf is the freezing temperature of seawater. If ice (and possibly snow) are present,
the effective back radiation heat flux is no longer computed by Equation (16.11) but via

Qebr = αTX4 (16.14)

in which TX either the ice temperature Ti or the snow temperature Ts , which depends on the
occurrence of snow on top of the ice layer (threshold thickness: 1 mm). In case of snow on
the ice, the ratio of the conductive coefficient ki over the ice thickness hi in Equation (16.12)
changes to (ki ks )/(hi ks + hs ki ), with hs and ks the thickness of the snow layer and the
thermal conductive coefficient for snow, respectively. We will from here refer either ratio as
k∗ /h∗ . A value of 2.04 W m−1 K−1 is applied for ki and 0.31 W m−1 K−1 for ks . Note that
the above-described iterative procedure is often applied in sea-ice models, e.g.: Wang et al.
(2005), Mellor and Kantha (1989). By defining TX = Tp + ∆T , with Tp the previous value
4
of TX and linearizing Equation (16.11) in ∆T via TX = Tp4 + 4Tp3 ∆T , the temperature TX
can be determined by iteration, via

k∗ k∗
Qtot without ebr − αTp4 − 4αTp3 ∆T = − Tp + ∆T (16.15)
h∗ h∗
Next, Equation (16.15) can be rewritten to
 
k∗ k∗
Qtot without ebr − αTp4 − Tp = ∆T 3
4αTp + (16.16)
h∗ h∗

Deltares 238 of 562

 Ice modelling in D-Flow FM

resulting in an air temperature correction ∆T per iteration as follows

k∗
Qtot without ebr − αTp4 − T
h∗ p
∆T = k∗
(16.17)
4αTp3 + h∗

In subroutine preprocess_icecover.f90 this is coded with the following variables (units

in brackets)

coef1 = αTX4 [J m−2 s−1 ] (16.18)

coef2 = 4αTX3 [J m−2 s−1 K−1 ]

T
(16.19)
−2 −1 −4
Qlong_ice = α [J m s K ] (16.20)
conduc = k∗ [J2 m−2 s−2 K−2 ] (16.21)
−1 −1
D_ice = h∗ [J s K ] (16.22)
AF qh_air2ice = Qtot without ebr [J m−2 s−1 ]
Qlong = Qebr [J m s ] −2 −1
(16.23)
(16.24)

After convergence the back radiation Qbr is computed via

Qbr = coef1 + coef2∆T (16.25)

Since Qtot without ebr is known in advance of the iteration process, the total heat flux between
the air and the ice can now be computed; see Equations 16.12 and 16.13. In practice, we
observed that only two or three iterations for are typically required for convergence. In the
DR

code maximally five iterations are applied.

So far the heat flux between the air and the ice or snow layer has been described in this
section. Now we will focus on the computation of the heat flux beneath the ice. In grid cells in
which ice is present, the heat flux between the ice and the water reads

Qice-water = −CT z (Tf − Ts ) (16.26)

where Ts is the water temperature at the uppermost grid layer near the surface. The heat
transfer coefficient CT z is given by
r
u∗ z0 u∗ 2/3
CT z = with BT = 3Prt P (16.27)
BT + Prt ln(−z/z0 )/κ ν t
with u∗ the friction velocity, Prt a turbulent Prandtl number, z is the vertical coordinate cor-
responding to the temperature T , z0 the roughness length and κ the Von Karman constant.
The molecular sublayer correction is represented by BT , Pt is the molecular Prandtl number
and ν is the kinematic viscosity of water.

The freezing temperature of seawater Tf depends on the salinity concentration (Fofonoff and
Millard Jr., 1983) of the upper water layer has been taken from and reads
√
Tf = (−0.0575 + 0.001710523 S − 0.0002154996S)S (16.28)

with S the salinity concentration in ppt. This formula is also used in NEMO (Madec et al.,
2022). Noted that for fresh water (S = 0 ppt) the freezing point equals 0 °C.

Deltares 239 of 562

 Ice modelling in D-Flow FM

16.3 Ice effect on wind drag

The wind drag assuming open water Cd,w is computed as described in section 15.1.2. Sub-
sequently, we have implemented 6 options to compute the effective wind drag including the
ice cover. These options can be specified by setting the keyword ModifyWindDrag in the
[ice] block of the mdu-file to the indicated string.
⋄ none: In this case there is no effect of the ice cover.
Cd,eff = Cd,w (16.29)

T
⋄ linear: In this case the drag is assumed to be proportional to the water area fraction
Aw .
Cd,eff = Cd,w Aw (16.30)

⋄ cubic: This option is consistent with the default "IceCube" option of ADCIRC (Chapman
AF and Massey).

Cd,eff = max(Cd,w , c0 + c1 Ai + c2 A2i + c3 A3i ) (16.31)

with c0 = 0.000 75, c1 = 0.0075, c2 = −0.009, and c3 = 0.002.

⋄ lupkes_birnbaum: This option follows Lupkes and Birnbaum (2005)
Cd,eff = Cd,w Aw + Cd,i Ai + Cd,f where (16.32)
Cd,i = 0.0015 (16.33)
1 1


Aw A0.8
w + 2 (1 − 2 Ai )
2
DR

Cd,f = 0.00034A2i (16.34)

31 + 90Ai Aw
⋄ andreas: This option follows Andreas et al (2010)
Cd,eff = c0 + c1 Ai Aw (16.35)

with c0 = 0.0015, and c1 = 0.002 233.

⋄ raysice: This option is consistent with the "RaysIce" option of ADCIRC (Chapman et
al).

Cd,eff = max(Cd,w , c0 + c1 Ai Aw ) (16.36)

with c0 = 0.001 25, and c1 = 0.005.

16.4 Ice effect on pressure

The ice cover exerts a pressure on the water column in addition to the atmospheric pressure,
such that the total pressure P at the surface becomes

P = Pa + Ai ρi ghi (16.37)

where Pa is the atmospheric pressure [Pa], Ai is the fraction of the area covered by ice [-],
ρi is the density of the ice [kg m−3 ], g is the gravitational acceleration [m s−2 ], and hi is the
thickness of the ice layer [m]. This effect can be switched off by setting ApplyPressure to
false.

Deltares 240 of 562

 Ice modelling in D-Flow FM

16.5 Ice effect on flow resistance

The vectorial boundary condition for the momentum equations 3.5 and 3.6 at the water-ice
interface (z = ζ ) is:
νV ∂u 1
= τ s,ice (16.38)
H ∂σ σ=1 ρ0
where
τ s,ice = ρ0 Ai Cd,ice |U flow − U ice | (U flow − U ice ) (16.39)

T
where ρ0 is the water density [kg m−3 ], Cd,ice is the drag coefficient [-] of the ice as given by
the user via IceFricValue, and U flow is the near-surface flow velocity [m s−1 ] and U ice
is the drift velocity of the ice [m s−1 ] (currently, always 0). This effect can be switched on by
setting ApplyFriction to true.
AF
16.6 Ice effect on surface exchange
The effect of ice on the surface heat exchange is included in the thermodynamic model and
always switched on, see section 16.2.2. The effect on evaporation is to be documented.
Snowfall is prescribed via the precipitation input. In case of precipitation and air temperatures
below zero, then this is considered as snowfall. Decay of the snow thickness is computed by
the thermodynamic model. Currently both rainfall and snowfall is applied is areas with ice in
case of precipitation and air temperatures below zero. In future this will be improved. The
switch ReduceSurfExch does not yet have an effect.
DR

16.7 Ice effect on waves

This effect can be switched on by setting ReduceWaves to true. This effect is currently
implemented as a reduction factor on the contribution of the wave forces to the momentum
equation. Hence, it will not reduce the effect of waves at other places, such as wave streaming.
It is foreseen that this implementation will be updated to more generally reduce the waves
where an ice cover is present. Note, SWAN can also include the effect of an ice cover, so in
coupled D-Flow FM-D-Waves simulation, it’s better to include the effect of the ice cover also
on the D-Waves side. Unfortunately, this option is only available for a forced ice cover, and
not yet for a dynamic ice cover.

16.8 Ice input options

This section describes how to switch on ice modelling in D-Flow FM. The main mdu-input file
of D-Flow FM contains several blocks of input, such as geometry, numerics and output. In
case of ice modelling an extra block with ice input has to be added, ice, as illustrated below.

[ice]
IceCoverModel = Semtner # Type of ice model (None, External, Semtner)

Currently, three options are available, namely:

⋄ None: No ice cover included. This is the default setting.
⋄ External: The ice cover thickness and ice area fraction are prescribed by the user via
external forcings.
⋄ Semtner: The ice thickness is dynamically computed by D-Flow FM, and varies in space
and time based on the meteorological input (air temperature, wind, cloudiness, relative
humidity, etc.). This option is based on the approach of Semtner Jr. (1976).

Deltares 241 of 562

 Ice modelling in D-Flow FM

Examples for the latter two cases are given in the following sections. However, first we’ll give
an overview of all keywords that can be specified in the ice block.

Table 16.1: Ice input keywords

Keyword Record description

ice

IceCoverModel specifies the ice cover model to be used

T
ApplyPressure logical flag indicating whether the ice pressure term should
be included (1 logical, default: true)
ApplyFriction logical flag indicating whether the ice friction term should be
included (1 logical, default: false)
AF
ReduceSurfExch logical flag indicating whether surface exchange should be
reduced (1 logical, default: false)
ReduceWaves logical flag indicating whether waves should be reduced (1
logical, default: false)
ModifyWindDrag effect of ice on wind drag (1 string)
⋄ none (default)
⋄ linear
⋄ cubic
⋄
DR
lupkes_birnbaum
⋄ andreas
⋄ raysice
IceDensity density of the ice (1 float, default: 917 kg m−3 )

IceAlbedo albedo of the ice cover (1 float, default: 0.75)

SnowAlbedo albedo of the snow cover (1 float, default: 0.9)

IceFricType type of friction specification at interface between ice and wa-

ter (1 string)
⋄ cdrag (default)
IceFricValue drag coefficient at the ice-water interface (1 float, default:
0.005)
AddIceToHis logical flag indicating whether the ice quantities should be
written to the his-file (1 logical, default: false)
AddIceToMap logical flag indicating whether the ice quantities should be
written to the map-file (1 logical, default: false)

Deltares 242 of 562

 Ice modelling in D-Flow FM

16.8.1 Ice modelling via External

In case of a prescribed ice thickness, the (old format) external forcings file (*.ext) has to be
extended with a reference to the ice model input. This file is connected in the input block
[external forcing] in the MDU-file, as illustrated below:

[external forcing]
ExtForceFile = ice_example.ext

T
The ice-related forcing in the *.ext file could for example be:

QUANTITY=sea_ice_thickness
FILENAME=ice_forcing.HICE
AF FILETYPE=6
METHOD=3
OPERAND=O

in which the file ice_forcing.HICE contains a space- and time-varying ice thicknesses on a
computational grid, similar to wind forcing as explained in Sections 12.2.2 and 12.2.3. The
suffix of the filename is arbitrary, but we prefer a representative name like HICE (thickness of
ice) or future options like AICE (area/fraction of grid cell covered by ice). An example is shown
below. In this example a 5-by-5 grid and only two points in time are used (0 and 6 hours after
T_start). The ice thickness in this example is 0.0, 1.0, 1.15 or 1.26 m. In this way, an external
DR

ice thickness can be prescribed. We remark that only an ice thickness can be prescribed and
not a snow thickness. The latter can have a significant effect on the ice growth or thaw, but
does not directly influence the water flow. Therefore, it is sufficient to only prescribe a fixed
ice thickness.

### START OF HEADER

filetype = meteo_on_curvilinear_grid
NODATA_value = -999.000
grid_file = extdata.grd
n_quantity = 1
### END OF HEADER
/* TIME (HRS) 0.0 20000101
0.00 1.00 1.00 1.00 0.00
0.00 1.15 1.15 1.00 0.00
0.00 1.15 1.15 1.00 0.00
0.00 1.00 1.00 1.00 0.00
0.00 1.00 1.00 1.00 0.00
/* TIME (HRS) 6.0 20000101
0.00 1.00 1.00 1.00 0.00
0.00 1.26 1.26 1.00 1.00
0.00 1.26 1.26 1.00 0.00
0.00 1.00 1.00 1.00 0.00
0.00 1.00 1.00 1.00 1.00

16.8.2 Ice modelling via Semtner

Via this option the ice thicknesses are computed by the computational engine of D-Flow FM,
based on the model input prescribed for the Composite heat flux model in D-Flow FM (temperature=5
in the mdu-file). See Chapter 11 for a more detailed explanation of this model. At present, ice
modelling in D-Flow FM is only possible in combination with the Composite heat flux model,
because this is currently the only heat flux model in D-Flow FM that computes temperatures
that can be compared with measurements (i.e. so-called absolute heat flux model).

Deltares 243 of 562

 Ice modelling in D-Flow FM

With this heat flux model, no additional input is needed to compute ice growth and thaw.
The input is the same as used for regular thermodynamic modelling with the Composite heat
flux model. This means that the required input for ice modelling is air temperature, relative
humidity and cloudiness. Furthermore, wind forcing input is used in the computation of ice
thicknesses. Thus, just adding IceCoverModel = Semtner to the mdu-file is enough
to include ice modelling in a simulation; see section 16.2.2. As the name reveals, the imple-
mented ice module is based on Semtner Jr. (1976).

In D-Flow FM it is possible to compute temperature below zero. This is of use for ice modelling,
because for example the freezing point of saline water with a salinity concentrations of 35 ppt

T
is close to −2 °C; see also Eq. (17). To enable negative temperature in D-Flow FM the two
keywords Allowcoolingbelowzero = 1 and Tempmin = -2 (or another negative
value) have to be added to the input block [physics]. In case of Tempmin = -999,
then the water temperature is at least the temperature of the freezing point, as computed
according to Equation 16.28.
AF The description above is sufficient for the computation of ice thicknesses without any occur-
rence of snow. However, snow can have a significant impact on the ice thickness. Snow on
top of ice acts like an ‘insulating blanket’ and can significantly reduce the growth of ice thick-
ness. In D-Flow FM, for the computation of snow thickness, rainfall input and air temperature
input are used. If there is any rainfall in a model, ideally specified with space- and time-varying
input, and if the air temperature is below zero, D-Flow FM assumes that this represents snow-
fall. In the example below, the snowfall (rainfall at air temperatures below zero) is 10 cm in
one day. Note that the below file is a time series file (*.tim), as described in section C.4.
DR

0.000000 0.0000000 ! rainfall or snowfall in mm/day

72000.0000 0.0000000
72001.0000 100.0000000
73441.0000 100.0000000
73450.0000 0.0000000
217440.0000 0.0000000

To illustrate, Figure 16.2 shows ice thicknesses (in blue) and snowfall (in red) for a cold winter.
In early December ice growth starts till a maximum thickness of 10 cm. This is followed by
a period of thaw, that makes the ice almost completely disappear. From mid-December a
second period of below-zero temperatures occurs, leading to a maximum ice thickness of
about 25 cm with snow and 35 cm without any snow. This clearly illustrates that the ice growth
is slowed down by a snow layer.

16.9 Postprocessing
Currently, ice quantities are only written to the map output file; this can be switched on by
setting AddIceToMap to true. Ice quantities cannot yet be written to the history output file,
i.e. the flag AddIceToHis does not yet have any effect. The ice quantities available on the
map output file are listed in Table 16.2. The names on the output file are a combination of the
names in the columns “long name” and “dimensions”.

Note that time series can be retrieved by selecting model output in an individual grid cell. This
was done to generate Figure 16.2. In general, the map output frequency will be much lower
than the history output frequency. However, time variation of ice and snow is much slower
than that of other quantities (water levels, currents, salinity, etc.).

Deltares 244 of 562

 Ice modelling in D-Flow FM

Figure 16.2: Illustration of computed ice thickness in case of no snow (in blue), ice thick-
ness in case of snow (in green) and snow thickness (in red)

T
AF
DR

Table 16.2: ice quantities on map output file

long name name on file units dimensions

Fraction of the surface area covered by floating ice - mesh2d_nFaces
Thickness of floating ice cover m mesh2d_nFaces
−2
Pressure exerted by the floating ice cover Nm mesh2d_nFaces
Thickness of the snow layer m mesh2d_nFaces

Deltares 245 of 562

 Ice modelling in D-Flow FM

16.10 Limitations
Ice modelling in D-Flow FM currently has the following limitations:

⋄ No history output for ice thickness and snowfall

⋄ No horizontal transport of ice
⋄ No open boundaries for ice
⋄ No restart of ice

T
AF
DR

Deltares 246 of 562

17 Coupling to external models via Basic Model Interface (BMI)
This chapter is on the coupling of hydrodynamics to external models. When running a coupled
model the DIMR program takes care of the exchange of data between components, and each
component will be addressed using BMI calls. Section 17.1 contains the technical details of
the D-Flow FM implementation of the BMI.

The other sections of this chapter go into more detail for a specific external model: coupling
with D-Waves in section 17.6, coupling to D-RTC in section 17.7, and coupling to ZSF (Sea
Lock Exchange) in section 17.8.

T
17.1 BMI interface to interact with the D-Flow FM model state
The D-Flow FM kernel shared library offers an API that implements the Basic Model Interface
(BMI). The BMI allows one to initialize, run, and finalize a model component via standardized
AF interface calls; furthermore it allows one to get and set various quantities such that model
components can dynamically react to the computed results. General details on the BMI can
be found in Peckham et al. (2013). This section discusses some of the D-Flow FM specifics.

Many variables in D-Flow FM’s model state can be inquired and changed via BMI calls. Setting
a variable can be done via a call to set_var(varname, userdata), which copies the
data from the userdata array to the D-Flow FM memory associated with the varname
variable. Alternatively, one may use a call to get_var(varname, xptr), which returns
a pointer to the requested variable, and directly assign new values to the D-Flow FM memory
from outside the running simulation. The latter approach may be faster because less data
needs to be copied.
DR

17.2 DIMR and the BMI

The DIMR program takes care of the exchange of data between components, and each
component will be addressed using BMI calls. The data to be exchanged is defined in the
<dimr.xml> configuration file, under the <dimrConfig><coupler><item> elements.
More details on DIMR can be found in Deltares (2025m).

The variable names specified there need to be supported by the addressed component. For
instance, for the coupling to D-RTC (see Section 17.7) typically scalar quantities need to be
exchanged that are defined at specific locations (such as observation points or structures).
Since BMI only identifies variables by a unique variable name without any location selection,
D-Flow FM identifies both location and quantity by introducing compound variable names (not
to be confused with a compound structure). A compound variable name takes the form:

varname = "groupname/locationid/fieldname"

For example the variable name "weirs/Lith01/CrestLevel" will select the crest level
at the weir named "Lith01".

The groupname part of the variable name identifies the location or object type. Currently
known group names are listed below. Unless noted otherwise, please check Section 17.3 for
the list of quantities supported for those groups of locations.
⋄ pumps
⋄ weirs
⋄ gates

Deltares 247 of 562

 Coupling to external models via Basic Model Interface (BMI)

⋄ generalstructures
⋄ sourcesinks
⋄ observations (observation points, see Section 17.4)
⋄ crosssections (observation cross sections, see Section 17.4)
⋄ laterals (see Section 17.5)

The locationid part of the variable name is the unique identifier of the intended object.
More details on the specific identifier used can be found in the subsequent sections on the
various object groups. The fieldname identifies the quantity at the selected location. Which

T
quantities are supported depends on the groupname.

17.3 BMI access to hydraulic structure data in D-Flow FM

To access quantities defined at structures use a compound variable name as explained in Sec-
AF tion 17.2. The locationid part of the compound variable name is, for hydraulic structures,
equal to the id key in the structure input file (Table C.12). Which quantities can be addressed
via the BMI, depends on the structure type indicated by the groupname. Table 17.1 lists the
supported field names for each hydraulic structure group.

Table 17.1: Supported compound variable fields for hydraulic structures in D-Flow FM via
BMI.

Group Field name Access Remark

name
pumps
DR

Capacity read-write Only for non-staged pumps. Prescribed

capacity, not necessarily actual dis-
charge.
weirs
CrestLevel read-write
gates
CrestLevel read-write
GateHeight read-write
GateLowerEdgeLevel read-write
GateOpeningWidth read-write
generalstructures
CrestLevel read-write
GateHeight read-write
GateLowerEdgeLevel read-write
GateOpeningWidth read-write
longculverts
ValveRelativeOpening read-write
sourcesinks
Discharge read-write Prescribed discharge, not necessarily
actual discharge.
ChangeInSalinity read-write Prescribed change, not necessarily ac-
tual change.
ChangeInTemperature read-write Prescribed change, not necessarily ac-
tual change.

Deltares 248 of 562

 Coupling to external models via Basic Model Interface (BMI)

17.4 BMI access to observations in D-Flow FM

To access quantities defined at observation points and observation cross sections use a com-
pound variable name as explained in Section 17.2. The locationid for observation points
should match the name specified in the relevant input file (See Section F.2.2). All observa-
tion point names must be unique when accessing the data via BMI. The same holds for the
locationid for observation cross sections (See Section F.2.4).

Table 17.2 lists the supported field names for each observation group. All supported vari-
ables/fields are read-only, evidently, as observations are only ’observing’ the flow. Typically,

T
these variables are used as input to hydraulic triggers in an RTC-coupling.

Table 17.2: Supported compound variable fields for observations in D-Flow FM via BMI.

Group Field name Access Remark

name
AF observations
water_level read-only
Observation points

water_depth read-only
velocity read-only
discharge read-only
salinity read-only Only when salinity transport is on.
temperature read-only Only when temperature transport is on.
<tracername> read-only Only when that named tracer is in the
model.
DR

crosssections Observation cross sections

discharge read-only Space-integrated along cross section.
velocity read-only Space-averaged along cross section.
water_level read-only Space-averaged along cross section.
water_depth read-only Space-averaged along cross section.

17.5 BMI access to forcings in D-Flow FM

To access quantities defined as local forcings (currently only lateral discharges) use a com-
pound variable name as explained in Section 17.2. The locationid for lateral discharges
should match the id specified for them in the external forcings input (See Section C.6.2.2).
Table 17.3 lists the supported field names for each forcing group.

Table 17.3: Supported compound variable fields for forcings in D-Flow FM via BMI.

Group Field name Access Remark

name
laterals
water_discharge read-write Prescribed discharge, not necessarily
actual discharge (when negative).
water_level read-only Water level, averaged value over the
nodes in the lateral.
water_volume read-only Total water volume per layer, for each
lateral.
water_discharge_per_layer
(continued on next page)

Deltares 249 of 562

 Coupling to external models via Basic Model Interface (BMI)

Group Field name Access Remark

name
(continued from previous page)
read-write Prescribed discharge, distributed over
the layers.
incoming/<constituent> read-write Concentration of a transported quantity
in incoming direction, array with 1 value
per layer.
outgoing/<constituent> read-only Concentration of a transported quan-
tity in outgoing direction, averaged value

T
over the lateral, per layer.

Remark:
⋄ <constituent> can be water_salinity, water_temperature or <tracername>.
AF
17.6 Coupling with D-Waves (SWAN)
This section is on the coupling of hydrodynamics and waves. Full documentation on D-Waves
is available in its own User Manual; this section is limited to the details of running coupled
flow-wave models, and the physical interaction processes between the two of them.

Restriction:
⋄ D-Flow FM runs integrated with D-Waves provided that only triangles or quadrangles
are applied in the D-Flow FM model grid. In case of pentagons or hexagons a coupling
DR

with D-Waves isn’t possible.

We remark that a coupled flow-wave model always consists of the combination of a hydrody-
namic model with an unstructured grid (D-Flow FM) coupled to a wave model with a structured
grid (SWAN). D-Flow FM cannot be coupled yet to a wave model with a unstructured grid (for
example UNSWAN).

17.6.1 Getting started

With respect to waves, offline and online results into:
1 offline: First, a separate D-Waves computation is executed, resulting in a communication
file (com-file) containing wave data. Then a D-Flow FM computation is executed, using
the wave data from the com-file.
2 online: D-Flow FM computations are alternated with D-Waves calculations. D-Flow FM
writes flow data to the com-file, D-Waves uses this flow data for the wave calculation and
writes wave data to the com-file. D-Flow FM uses the updated wave data.

Both modes are started by executing DIMR with a <dimr_config.xml> file as argument. This
file prescribes the mode and when the D-Flow FM computation should be paused to perform
a D-Waves calculation. From within the working directory, the following run-scripts in the
installation directory can be called:
⋄ On Windows:
<Your installation base dir>\x64\bin\run_dimr.bat
⋄ On Linux:
<Your installation base dir>/lnx64/bin/run_dimr.sh
⋄ On Windows, a computation with D-Flow FM in parallel using MPI:
<Your installation base dir>\x64\bin\run_dimr_parallel.bat

Deltares 250 of 562

 Coupling to external models via Basic Model Interface (BMI)

⋄ On Linux, submitting a job on the Deltares cluster (sequential and parallel):

<Your installation base dir>/lnx64/bin/submit_dimr.sh
This script can be used for clusters outside Deltares too, but system specific modifications
will be needed.

Note: Example models, with run scripts, are included in the (open source) code. After
registering yourself at https://oss.deltares.nl/, you can have a look at:
https://svn.oss.deltares.nl/repos/delft3d/trunk/examples
/12_dflowfm/test_data/e100_f02_c02-FriesianInlet_schematic_FM_wave

T
17.6.1.1 Input D-Flow FM
AF Optionally add the following lines to the .mdu file:

[numerics]
Epshu = 0.05 # Input for threshold water depth for wet and dry cells

[waves]
Wavemodelnr = 3 # Wave model nr, 0=no, 1=fetch/depth limited hurdlestive,
2=youngverhagen, 3 = D-Waves, 4=wave group forcing
Rouwav = FR84
Gammax = 0.5 # Maximum wave height/water depth ratio
waveSwartDelwaq = 0 # Communicate bed shear stress to D-Water Quality.
0=Parametrization WCI Soulsby (1997) using Rouwav;
1=linear sum taucur+tauwav;
2=morphological bed shear stress. Default 0.
DR

[output]
ComInterval = 1200. # (Fixed) Interval with which the wave
communication file is written for
wavemodelnr=3. Default: dtuser
ComOutputTimeVector = compoints.ctv # File with number of
prefixed communication
timepoints, only for wavemodelnr=3
EulerVelocities = 1 # 0 (default): GLM, 1: Euler.
Only relevant when using waves

Description:
Wavemodelnr Key switch to enable wave modelling. Use “3” for wave data from
D-Waves (online or offline) and passing hydrodynamic data to D-
Waves (online only). A file will be generated automatically named
<”runid”_com.nc> to exchange data.
Rouwav Necessary to include bed shear-stress enhancement by waves. See
also Delft3D-FLOW manual.
EulerVelocities Optional flag to write Eulerian velocities to the D-Flow FM map file.
Currently, only Eulerian values will be written for the cell centre veloc-
ity x-component and y-component (parameters ucx and ucy). Check
that the ”long_name” contains the word ”Eulerian”.
Epshu Optionally overwrite the default value of “1.0e-4”. Depending on your
model, the default value of Epshu in combination with modelling
waves may lead to huge local velocities near (almost) dry points.
This will result in very small time steps. Increasing Epshu might be
a reasonable workaround.
Gammax Optionally overwrite the default value of “1.0”. Depending on your
model, the default value of Gammax may lead to huge local veloc-

Deltares 251 of 562

 Coupling to external models via Basic Model Interface (BMI)

ities in shallow water. Decreasing Gammax might be a reasonable

workaround.
waveSwartDelwaq Optional flag to communicate bed shear stresses from Delft3D-FLOW
to D-Water Quality. Possible values are 0, 1 or 2. Only applicable if
wavemodelnr>0. The default is set to 0. If waveSwartDelwaq
equals 0, the bed shear stress is taken from the flow model. In prac-
tice, this means that the wave-current interaction is parametrized
according to (Soulsby, 1997) and the resulting bed shear stress is
communicated to D-Water Quality. A simpler approach is obtained
using waveSwartDelwaq equal to 1. In that case, the shear

T
stress that is communicated is the linear sum of the bed shear stress
due to currents and the shear stress due to waves. In case of
waveSwartDelwaq equal to 2, the maximum shear stress over
the wave cycle (Soulsby, 1997) is communicated.
ComInterval Optional entry to set the interval with which the communication file to
AF D-Waves is written. When this is not specified, the communication
file is written with DtUser intervals. Can be specified as an array:
interval, start time, stop time in seconds since RefDate. Not compat-
ible with ComOutputTimeVector.
ComOutputTimeVector Optional entry to the file (.ctv) containing fixed time points to write
the communication file for the online wave coupling. Can be used
in combination with varying DIMR communication time points (Sec-
tion 17.6.1.3). Time points in seconds since RefDate. Not compati-
ble with ComInterval.
DR

17.6.1.2 Input D-Waves

Optionally add the following lines to the .mdw file:

[Output]
MapWriteNetCDF = true
COMFile = ../fm/dflowfmoutput/fff_com.nc
NetCDFSinglePrecision = false
locationFile = ../fm/loo_obs.xyn
writeTable = true

Description:
MapWriteNetCDF Default value “false”, resulting in no output written in netCDF format.
The coupling with D-Flow FM is only implemented for netCDF format,
so this flag must be set to “true” when being coupled with D-Flow FM.
COMFile Necessary reference to the file being used to communicate data to
and from D-Flow FM. The name must exactly match with the name
of the com-file being generated by D-Flow FM.
NetCDFSinglePrecision Optional flag to write data in single precision instead of double
precision. Default value is “false”. Might be useful to decrease the
size of the com-file or to compare with a Delft3D-FLOW computation.
locationFile Optional reference to observation points in D-Flow FM. When in
combination with the “writeTable” flag, D-Waves will produce a his-
tory file in netCDF format for these observation points.
writeTable Optional flag to force SWAN to produce an output file in table format
for each set of locations specified in a locationFile. Default value is
“false”.

Deltares 252 of 562

 Coupling to external models via Basic Model Interface (BMI)

17.6.1.3 Input DIMR

Both D-Flow FM and D-Waves are used as dynamic libraries (DLL’s on Windows, so’s on
Linux). DIMR is a small executable steering both dynamic libraries. Its input file, usually
called “dimr_config.xml”, looks like this:
<?xml version="1.0" encoding="iso-8859-1"?>
<dimrConfig xmlns="http://schemas.deltares.nl/dimrConfig"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.deltares.nl/dimrConfig
http://content.oss.deltares.nl/schemas/d_hydro-1.00.xsd">
<documentation>

T
<fileVersion>1.00</fileVersion>
<createdBy>Deltares, Coupling team</createdBy>
<creationDate>2015-05-20T07:56:32+01</creationDate>
</documentation>

<control>
<parallel>
AF <startGroup>
<time>0.0 60.0 99999999.0</time>
<coupler name="flow2rtc"/>
<start name="myNameRTC"/>
<coupler name="rtc2flow"/>
</startGroup>
<startGroup>
<time>0.0 3600.0 99999999.0</time>
<start name="myNameWave"/>
</startGroup>
<start name="myNameDFlowFM"/>
</parallel>
</control>
DR

<component name="myNameDFlowFM">
<library>dflowfm</library>
<process>0 1 2</process>
<mpiCommunicator>DFM_COMM_DFMWORLD</mpiCommunicator>
<workingDir>fm</workingDir>
<inputFile>weirtimeseries.mdu</inputFile>
<setting key="verbose" value="INFO"/>
</component>
<component name="myNameWave">
<library>wave</library>
<process>0</process>
<workingDir>wave</workingDir>
<!-- component specific -->
<inputFile>weir.mdw</inputFile>
</component>
<component name="myNameRTC">
<library>RTCTools_BMI</library>
<process>0</process>
<workingDir>rtc</workingDir>
<!-- component specific -->
<inputFile>.</inputFile>
</component>

<coupler name="flow2rtc">
<sourceComponent>myNameDFlowFM</sourceComponent>
<targetComponent>myNameRTC</targetComponent>
<item>
<sourceName>observations/Upstream/water_level</sourceName>
<targetName>input_ObservationPoint01_water_level</targetName>
</item>
</coupler>
<coupler name="rtc2flow">
<sourceComponent>myNameRTC</sourceComponent>
<targetComponent>myNameDFlowFM</targetComponent>

Deltares 253 of 562

 Coupling to external models via Basic Model Interface (BMI)

<item>
<sourceName>output_weir_crest_level</sourceName>
<targetName>weirs/weir01/crest_level</targetName>
</item>
</coupler>
</dimrConfig>

Description:
<control> Specifies the workflow of the deltaresHydro executable. It indicates which com-
ponents are started in which order. If the data transfer is to be arranged by

T
the main program DIMR, then a coupler should be included. The main <con-
trol> block is a sequential block; this means that each component is initialized,
time stepped, and finalized before the next component starts. For each com-
ponent/coupler listed inside the <control> block there will be a corresponding
component/coupler specification block defined below.
AF
<parallel> Within a <parallel> tag the components are started concurrently (if the mpi pro-
cess id’s listed per component don’t overlap) or executed synchronously in se-
quence (first all initialize, then time stepping, and to conclude all finalization
calls). The order of the components is retained.
<start> A <parallel> block contains exactly one <start> component, defining the start
and end time of the simulation. This is the component inside the <parallel> block
with the smallest time step and can be denoted as the ”master-component”. All
other components must be defined with a <startGroup> and can be denoted as
a ”slave-component”.
<startGroup> A <startGroup> should be used if a component (possibly including couplers)
should only be executed at a subset of simulation time steps.
DR

<time> Start-, step- and stop-time (in seconds) at which this slave-component should
be executed. The times are relative to the times of the master-component. Thus
a start-time of 0.0 always refers to the start time of the master-component and
a stop-time of ”infinity” always refers to the end time of the master-component.
Alternative: Instead of specifying start-, step- and stop-time it is also an op-
tion to specify the name of a tim-file containing all times for which this slave-
component should be executed. Example line in file “dimr_config.xml”:
<time>wave_computations.tim</time>

Example content of file “wave_computations.tim”:

10800.0
14400.0
16200.0

Restrictions:
⋄ The times in the tim-file must be in increasing order
⋄ The times in the tim-file are relative to the times of the master-component
⋄ The tim-file must contain at least 3 times
<component name="myComponentName"> Component specification block. ”myCompo-
nentName” is free to be defined by the user. It must match exactly with the
reference in the <control> block above. The name of a component must be
unique.
<library> Reference to the component to be executed. Currently ”flowfm”, ”wave” and
”FBCTools_BMI” are supported. The name must match exactly the name of
the related dll/so (excluding prefixes (e.g. “lib”) and suffixes (e.g. “.dll” or “.so”)).
The library should be located in the search path, or it may include an absolute or
relative path. Multiple <component> blocks may refer to the same component
to be executed.

Deltares 254 of 562

 Coupling to external models via Basic Model Interface (BMI)

<process> Optional list of the ids of the mpi processes that should be used to run the
component. If not specified, then the component will run only in process “0”
(i.e. non-parallel). The processes may be specified as a space separated list
with series compressed using colons e.g. “16:31” represents processes “16 17
18” up to “31”.
<mpiCommunicator> D-Flow FM specific flag. Mandatory only when this D-Flow FM com-
ponent should run a parallel (partitioned) model. Note that this is unrelated to
the <parallel> tag as introduced above.
<workingDir> Specification of the working directory of this <component>, relative to the
location of the “dimr_config.xml” file. The workingDir is the base/root directory

T
of all input and output files for the component. All other files will be located
RELATIVE TO this folder. If not specified, then workingDir will be equal to the
folder of the configuration file.
<inputFile> Specification of the input file of this <component>, relative to <workingDir>:
D-Flow FM: mdu-file, D-Waves: mdw-file, D-RTC: .
AF <coupler name="myCouplerName"> Coupler specification block. ”myCouplerName” is free
to be defined by the user. It must match exactly with the reference in the <con-
trol> block above. The name of a coupler must be unique.
<sourceComponent> Identifies which component provides the data.
<targetComponent> Identifies which component needs to receive the data. The coupler
runs on the superset of the processes configured for the source and target
components.
<item> For each quantity to be exchanged, the name in the source component and the
name in the target component are specified. To support recursive components,
a directory syntax is used with forward slashes. If a name includes a forward
slash, then it needs to be escaped using a backward slash, like \/; if a name
DR

includes a backward slash, then it needs to be escaped with a backward slash,

like \\.
<sourceName> Identifies which parameter will be sent at the source component side.
<targetName> Identifies which parameter will be received at the target component side.
<setting> DIMR way to provide the command line options in the form of key - value pairs.
Currently only support for the keys processlibrary, bloomspecies and
verbose.

17.6.1.4 Online process order

When D-Flow FM runs online in alternation with D-Waves and D-RTC, process steps can
be identified, where the order as prescribed in “dimr_config.xml” is respected as much as
possible. The process order of the example “dimr_config.xml” file in the section above is:
1 D-Flow FM::Init
D-Flow FM is initialized. Grid- and Flow-data is written to the netCDF com-file.
Even though D-Flow FM is not the first component in the example config-file, it must be
the first component to be initialized, because the initialization results may be needed when
other components are initialized. This is implemented as an exceptional rule: The master-
component is always the first component to be initialized.
2 D-RTC::Init
D-RTC is initialized using (only) D-RTC input. Data from other components is not initialized
yet; default values are used.
3 D-Waves::Init
D-Waves is initialized. Grid- and Flow-data created by D-Flow FM::Init is read from the
com-file. Grid conversion factors are generated. The factors for the conversion from the
(structured!) wave grid to the (unstructured) flow grid are calculated inside D-Waves.
The factors for the conversion from the (unstructured) flow grid to the (structured) wave

Deltares 255 of 562

 Coupling to external models via Basic Model Interface (BMI)

grid are calculated by ”ESMF_RegridWeightGen” via the execution of script <ESMF_-

RegridWeightGen_in_Delft3D-WAVE.bat> (Windows) or <ESMF_RegridWeightGen_in_-
Delft3D-WAVE.sh> (Linux).

4 D-RTC::Step
A D-RTC computation is performed at time “0.0”: Data is communicated (by DIMR) from
D-Flow FM to D-RTC, the actual D-RTC computation is executed, data is communicated
(by DIMR) from D-RTC to D-Flow FM.
5 D-Waves::Step
A D-Waves calculation is performed at time “0.0”: Flow data is read (by D-Waves) from

T
the com-file and converted to the wave grid(s). SWAN input files are written, a SWAN
calculation is started by executing script <swan.bat> (Windows) or <swan.sh> (Linux),
SWAN output files are read, wave-data is converted to the flow grid and written to the
com-file (by D-Waves).
6 D-Flow FM::Step
AF A D-Flow FM calculation is performed: The com-file is checked for wave data to be
used/updated. The simulation time will proceed from “0.0” to “60.0” (next time that another
component should be executed). Flow-data is written to the com-file (by D-Flow FM).
7 D-RTC::Step, D-Flow FM::Step
A D-RTC computation is performed after every “60.0” seconds. Then a D-Flow FM com-
putation is performed and the simulation time will proceed another “60.0” seconds. This
continues untile the simulation time has progressed for “3600.0” seconds.
8 D-RTC::Step, D-Waves::Step, D-Flow FM::Step
A D-RTC computation is performed, then a D-Waves computation, then a D-Flow FM
computation. The simulation time will proceed another “60.0” seconds and the next D-
RTC computation can start.
DR

9 D-RTC::Finish
D-RTC is finished at the end of the simulation.
10 D-Waves::Finish
D-Waves is finished at the end of the simulation.
11 D-Flow FM::Finish
D-Flow FM is finished at the end of the simulation.

17.6.1.5 Related files

Below is an overview of the related files in the default directory structure. In this example the
runid is set to foo.
<testcaseroot>
dimr_config.xml Configuration file, input for DIMR
<fm> Work directory for D-Flow FM
foo.mdu D-Flow FM input file
<dflowfmoutput> D-Flow FM output directory
foo_com.nc Communication file, written/read by both D-Flow FM and D-Waves
<rtc> Work directory for D-RTC
settings.json D-RTC input file (must have exactly this name)
<xml_dir> D-RTC directory containing xml input/output files and csv output file
<xsd_dir> D-RTC directory containing xsd input files
<wave> Work directory for D-Waves
foo.mdw D-Waves input file
TMP_ESMF*_source.nc Temporary input file for ESMF_Regridder, created by D-
Waves
TMP_ESMF*_destination.nc Temporary input file for ESMF_Regridder, created

Deltares 256 of 562

 Coupling to external models via Basic Model Interface (BMI)

by D-Waves
TMP_ESMF*_weights.nc Resulting weights file, created by ESMF_Regridder, read
by D-Waves
PET0.RegridWeightGen.Log ESMF_Regridder log file
swn-diag.foo SWAN log file

17.6.1.6 SWAN output file as input

This is alpha functionality.

T
Instead of coupling D-Flow FM to D-Waves, a SWAN output file, in NetCDF format, can be
used. Space and time varying data can be read and used as input. Currently this method can
be used to add (wave related) bed shear stress to the D-Water Quality simulation inside D-
Flow FM (wavemodelnr = 6), and to add wave forcing and bed shear stress contributions
to a 2DH D-Flow FM model (wavemodelnr = 7).
AF wavemodelnr = 7
Currently, the following input specification is accepted in the ExtForceFile and the .mdu
file:

Example old style ExtForceFile:

* comments
* comments

QUANTITY = wavesignificantheight
DR

FILENAME = swanout.nc
VARNAME = sea_surface_wave_significant_height
FILETYPE = 11
METHOD = 3
EXTRAPOLATION_METHOD = 1
OPERAND = O

QUANTITY = waveperiod
FILENAME = swanout.nc
VARNAME = tps
FILETYPE = 11
METHOD = 3
EXTRAPOLATION_METHOD = 1
OPERAND = O

Where the quantities (wavesignificantheight and waveperiod) are dictated by D-

Flow FM and the varnames (sea_surface_wave_significant_height and tps)
are chosen by SWAN in its NetCDF output file.

Example lines in .mdu file:

[waves]
Wavemodelnr = 6 # 0: none,
1: fetch/depth limited hurdlestive,
2: Young-Verhagen,
3: SWAN via D-Waves,
5: uniform,
6: SWAN-NetCDF
Rouwav = FR84
FlowWithoutWaves = true # True: Do not use Wave data in the flow computations,
it will only be passed through to D-WAQ
WaveSwartDelwaq = 1

Deltares 257 of 562

 Coupling to external models via Basic Model Interface (BMI)

Currently, only the combination of parameters in the example above is tested.

Note: An example model, with run scripts, is included in the (open source) code. After
registering yourself at https://oss.deltares.nl/, you can have a look at:
https://svn.oss.deltares.nl/repos/delft3d/trunk/examples
/12_dflowfm/test_data/FriesianInlet_schematic_SWAN_nc/FM

wavemodelnr = 7
Depending on the [waves] waveforcing keyword, different wave quantities are required
to be specified in the (old-style) external forcing file (Table 17.4). For every Waveforcing

T
value, every variable needs to be present in the ExtForceFile for the functionality to work.
Note that you have to provide the variable name of the significant wave height together with
the wave direction in order to interpolate the directions correctly. You can do this as follows:

Example lines in .mdu file:

AF
[waves]
Wavemodelnr = 7
Rouwav = FR84
Waveforcing = 1

Example lines in (old-style) .ext file:

DR

* comments
* comments

QUANTITY = wavedirection
FILENAME = output_swan2D_permuted.nc
VARNAME = sea_surface_wave_from_direction sea_surface_wave_significant_height
FILETYPE = 11
METHOD = 3
EXTRAPOLATION_METHOD = 1
OPERAND = O

QUANTITY = waveperiod
FILENAME = output_swan2D_permuted.nc
VARNAME = tm01
FILETYPE = 11
METHOD = 3
EXTRAPOLATION_METHOD = 1
OPERAND = O

QUANTITY = wavesignificantheight
FILENAME = output_swan2D_permuted.nc
VARNAME = sea_surface_wave_significant_height
FILETYPE = 11
METHOD = 3
EXTRAPOLATION_METHOD = 1
OPERAND = O

QUANTITY = xwaveforce
FILENAME = output_swan2D_permuted.nc
VARNAME = eastward_wave_force
FILETYPE = 11
METHOD = 3
EXTRAPOLATION_METHOD = 1
OPERAND = O

QUANTITY = ywaveforce
FILENAME = output_swan2D_permuted.nc
VARNAME = northward_wave_force
FILETYPE = 11

Deltares 258 of 562

 Coupling to external models via Basic Model Interface (BMI)

METHOD = 3
EXTRAPOLATION_METHOD = 1
OPERAND = O

Table 17.4: Entries in ExtForceFile for use with wavemodel 7. The entries in the
Varname column that should be present in the NetCDF file depend on the
Waveforcing value in the .mdu file.

Waveforcing Quantity Varname

T
1 wavedirection theta0
sea_surface_wave_from_direction
waveperiod any valid period field
waveheight sea_surface_wave_significant_height
AF 2
xwaveforce
ywaveforce
wavedirection
eastward_wave_force
northward_wave_force
theta0
sea_surface_wave_from_direction
waveperiod any valid period field
waveheight sea_surface_wave_significant_height
totalwavedissipation total_energy_dissipation
3 wavedirection theta0
DR

sea_surface_wave_from_direction
waveperiod any valid period field
waveheight sea_surface_wave_significant_height
xwaveforce eastward_wave_force
ywaveforce northward_wave_force
wavebreakerdissipation depth_induced_surf_breaking_energy_dissipation
whitecappingdissipation whitecapping_energy_dissipation

In this way, the change in momentum due to the presence of waves can be accounted
for by using the spatial radiation stress gradients (waveforcing=1), the total dissipation
(waveforcing=2), or by distributing the wave pressure forces over the water column (waveforcing=3).
This is elaborated on in the next section (section 3.8).

17.7 Coupling with D-RTC (FBC-Tools)

This section is on the coupling of hydrodynamics and real-time control — more specific: feed-
back control — of hydraulic structures.

17.7.1 Introduction
A coupled flow-rtc model can be run either as an Integrated Model from within the D-Flow FM
User Interface, or from the commandline using the DIMR program (Deltares Integrated Model
Runner).

In case of a flow-rtc coupling

⋄ the flow model will exchange for example Water levels

Deltares 259 of 562

 Coupling to external models via Basic Model Interface (BMI)

⋄ subsequently, the rtc model will prescribe for example the Crest level of a controlled struc-
ture, based on the exchanged water levels
⋄ in case of an online coupling this Crest level will influence the hydrodynamic simulation.

17.7.2 Getting started

17.7.2.1 User interface: the first steps

First, the user must add a real-time control model to the flow-fm model. The Project window
will look like this.

T
AF
Figure 17.1: An Integrated model in the Project window
DR

Secondly, the user will model the control flow for an hydraulic structure. This may look like
this.

Figure 17.2: Example of a Control flow in D-RTC

Full documentation on D-RTC is available in its own User Manual. This section is limited to
the details of running coupled flow-rtc models.

Deltares 260 of 562

 Coupling to external models via Basic Model Interface (BMI)

17.7.2.2 Input D-Flow FM

The hydraulic structures that are normally driven by scalar values or time series in <∗.bc>
files, will now be fed by D-RTC. Replace the timeseries file name by the realtime keyword
in the <structures.ini> file (section C.12):

[Structure]
type = weir # Type of structure
id = weir01 # Name of the structure
locationFile = weir01.pli # *.pli; Polyline geometry definition for 2D structure
crestLevel = realtime # Crest level in [m]

T
Also, the MDU file may optionally contain an observation file and/or a cross section file, such
that D-RTC’s triggers can be set to respond to the computed values at these locations.
AF [output]
ObsFile
CrsFile
= obs.xyn
= river_crs.pli

17.7.2.3 Input D-RTC

The input of D-RTC consists of several <∗.xml> files and a toplevel <settings.json>. We
refer to the D-RTC User Manual (Deltares, 2025e) for further details.
DR

17.7.2.4 Input DIMR

In Section 17.6.1.3, details on a coupled flow-rtc-wave model are presented. This can serve
as an example for a flow-rtc coupling, by leaving out all wave-related fragments.

17.7.2.5 Online process order

This is discussed in Section 17.6.1.4 for a coupled flow-rtc-wave model. This can serve as an
example for a flow-rtc coupling, by leaving out all wave-related fragments.

17.8 Coupling with module for Sea Lock Exchange

17.8.1 Introduction
The Wanda-Locks software suite of Deltares is available for the simulation of salt intrusion
in sea locks, and it can be coupled to Delft3D-FLOW via the COSUMO toolbox. However,
this results into very computationally intensive simulations. Therefore, another approach has
been developed that is much less computationally demanding, called ZSF. D-Flow FM can
be coupled to the "Sea Lock Exchange" software program of Deltares, which is called the
"Zeesluisformulering" (ZSF) in Dutch. The ZSF software is available in Python and as a C-
library and has been applied to many sea locks.

Based on the water level and the salinity concentration at lateral locations, discharges ‘from
sea to lake’ and ’from lake to sea’ are computed by the ZSF (Sea Lock Exchange). In D-
Flow FM these discharges are modelled via laterals. The sea lock itself is represented in the
D-Flow FM model area as a closed or dry area, as illustrated in Figure 17.3.

At this moment, component zsf.dll is not included in the release of Delft3D Flexible Mesh Suite.
It is a Deltares tool, for which the source code and build instructions are available from https:

Deltares 261 of 562

 Coupling to external models via Basic Model Interface (BMI)

T
Figure 17.3: An example of a simple D-Flow FM model in the Graphic User Interface
AF (GUI). The sea lock is in the middle, the lake on the left side and the sea on
the right side.

//github.com/Deltares-research/libzsf. The technical documentation of ZSF can be found at

https://libzsf.readthedocs.io/en/latest/theory/index.html.

17.8.2 Coupling of D-Flow FM with ZSF (Sea Lock Exchange)

A coupled D-Flow FM-ZSF model can be run as an Integrated Model from within the D-
Flow FM User Interface, or from a command prompt using the DIMR program (Deltares Inte-
DR

grated Model Runner).

In case of a coupled D-Flow FM-ZSF model

⋄ the D-Flow FM model and the ZSF model exchange water discharge and salinity through
laterals.
⋄ the D-Flow FM model provides boundary conditions to the ZSF model, i.e. water level
and salinity at the lake and sea sides. The ZSF model will in turn provide lateral input to
the D-Flow FM model, i.e. the discharge extracted from and the discharge and salinity
deposited to the lake and sea.
⋄ laterals in D-Flow FM may consist of multiple grid cells. All exchanged data is aggregated
into a single value per lateral before the exchange with ZSF.
⋄ in case of 3D models the exchange of water and salinity can be subdivided over multiple
layers.
⋄ it is advised to specify different lateral locations for inflow and outflow at both sides of
the sea lock, to prevent unphysical mixing in the D-Flow FM model. This results into four
laterals per sea lock.

Deltares 262 of 562

 Coupling to external models via Basic Model Interface (BMI)

17.8.3 Configuration of the model

Figure 17.3 shows a simple D-Flow FM model in which a sea lock is located in the middle of
a D-Flow FM model domain. The cells with red triangles represent the sea lock via dry points
in D-Flow FM and are therefore non-computational cells. In this example the lake is on the
left and the sea on the right side of the model. There are four lateral locations, denoted by
four blue polygons. For both the lake side and the sea side the lateral locations for inflow and
outflow are separated. In this example, all four laterals consists of two grid cells.

Remark: for administrative reasons it is necessary that the polygons for each lateral are in

T
separate polygon-files. When using the GUI to create a model this is automatically correct,
but the user should pay attention to this when creating or modifying a model by hand.

An example of a DIMR config file can be found here:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<dimrConfig xmlns="http://schemas.deltares.nl/dimr"
AF xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.deltares.nl/dimr
http://content.oss.deltares.nl/schemas/dimr-1.2.xsd">
<documentation>
<fileVersion>1.2</fileVersion>
<createdBy>Deltares, Coupling Team</createdBy>
<creationDate>2020-10-18T09:43:43.7803727Z</creationDate>
</documentation>
<control>
<parallel>
<startGroup>
<time>0 300 172800</time>
<coupler name="flow_to_zsf"/>
DR

<start name="SeaLockExchange"/>
<coupler name="zsf_to_flow"/>
</startGroup>
<start name="FlowFM"/>
</parallel>
</control>
<component name="SeaLockExchange">
<library>zsf</library>
<workingDir>zsf</workingDir>
<inputFile>zsf_cycle-average.ini</inputFile>
</component>
<component name="FlowFM">
<library>dflowfm</library>
<workingDir>dhydro</workingDir>
<inputFile>FlowFM.mdu</inputFile>
<mpiCommunicator>DFM_COMM_DFMWORLD</mpiCommunicator>
<process>0</process>
</component>
<coupler name="zsf_to_flow">
<sourceComponent>SeaLockExchange</sourceComponent>
<targetComponent>FlowFM</targetComponent>
<item type="pointer">
<sourceName>results/sealock_A/discharge_from_lake</sourceName>
<targetName>laterals/discharge_from_lake/water_discharge</targetName>
</item>
<item type="pointer">
<sourceName>results/sealock_A/discharge_to_lake</sourceName>
<targetName>laterals/discharge_to_lake/water_discharge</targetName>
</item>
<item type="pointer">
<sourceName>results/sealock_A/salinity_to_lake</sourceName>
<targetName>
laterals/discharge_to_lake/incoming/water_salinity
</targetName>

Deltares 263 of 562

 Coupling to external models via Basic Model Interface (BMI)

</item>
<item type="pointer">
<sourceName>results/sealock_A/discharge_from_sea</sourceName>
<targetName>laterals/discharge_from_sea/water_discharge</targetName>
</item>
<item type="pointer">
<sourceName>results/sealock_A/discharge_to_sea</sourceName>
<targetName>laterals/discharge_to_sea/water_discharge</targetName>
</item>
<item type="pointer">
<sourceName>results/sealock_A/salinity_to_sea</sourceName>
<targetName>

T
laterals/discharge_to_sea/incoming/water_salinity
</targetName>
</item>
</coupler>
<coupler name="flow_to_zsf">
<sourceComponent>FlowFM</sourceComponent>
AF <targetComponent>SeaLockExchange</targetComponent>
<item type="pointer">
<sourceName>
laterals/discharge_from_lake/outgoing/water_salinity
</sourceName>
<targetName>zsf_boundary_condition/sealock_A/salinity_lake</targetName>
</item>
<item type="pointer">
<sourceName>laterals/discharge_from_lake/water_level</sourceName>
<targetName>zsf_boundary_condition/sealock_A/head_lake</targetName>
</item>
<item type="pointer">
<sourceName>
DR

laterals/discharge_from_sea/outgoing/water_salinity
</sourceName>
<targetName>zsf_boundary_condition/sealock_A/salinity_sea</targetName>
</item>
<item type="pointer">
<sourceName>laterals/discharge_from_sea/water_level</sourceName>
<targetName>zsf_boundary_condition/sealock_A/head_sea</targetName>
</item>
</coupler>
</dimrConfig>

In the DIMR input file the specification of the exchange item looks like

<targetName>laterals/discharge_from_lake/water_discharge</targetName>
<sourceName>laterals/discharge_from_lake/water_salinity</sourceName>

These will be mapped onto the lateral that is specified in the <.ext> file as:

[lateral]
Id = discharge_from_lake
locationFile = discharge_from_lake.pol
discharge = realtime
applyTransport = 1

Keyword realtime indicates that the parameter receives its values from the coupled model
(ZSF in this example) and keyword applyTransport indicates that transport of salinity (or
temperature or tracers) through the lateral is taken into account.

Deltares 264 of 562

 Coupling to external models via Basic Model Interface (BMI)

17.8.4 Processing of the received lateral data items in D-Flow FM

In this section, we describe the processing of the lateral data items in D-Flow FM. ZSF expects
and returns a single value per lateral and per layer. In D-Flow FM, in the horizontal direction,
the single value from ZSF will be distributed over all cells in the lateral after exchange with
ZSF. In turn, the values of all the cells will be aggregated before exchanging them to ZSF.

Water volume
At each lateral location, the water volume is the water volume per horizontal layer, which is

T
computed as the sum of the volumes of the individual cells on this layer.

Distribution of the lateral discharge

Lateral discharge (per layer) is communicated between ZSF model and D-Flow FM model via
AF BMI. For each lateral location, after the D-Flow FM model receives the discharge value per
layer (from ZSF model), D-Flow FM distributes the discharge over all the cells in the lateral
volume defined by a polygon and a layer. The distribution is proportional to the available
volume in a cell.

The algorithm for distribution of the lateral discharge in a 3D model is as follows. (In case of
a 2D model, it can be regarded as only one layer model in the 3D model.) Let i_layer =
1, ..., kmx be the layer indices where kmx is the total number of layers in 3D models of D-
Flow FM. Moreover, let ncell be the total number of cells at one lateral location. The following
variables are needed for distributing the lateral discharge:
⋄ Volume for each cell at each layer, denoted by Vi_layer,i_cell .
DR

⋄ Total volume at layer i_layer, denoted by Vi_layer . Therefore,

ncell
X
Vi_layer,i_cell = Vi_layer .
i_cell=1

⋄ Discharge for each cell at each layer, denoted by Qi_layer,i_cell .

⋄ Total discharge at layer i_layer, denoted by Qi_layer . Therefore,
ncell
X
Qi_layer,i_cell = Qi_layer .
i_cell=1

The following relation holds:

Qi_layer,i_cell Vi_layer,i_cell
= . (17.1)
Qi_layer Vi_layer
Therefore, Qi_layer,i_cell can be computed by:

Vi_layer,i_cell
Qi_layer,i_cell = · Qi_layer . (17.2)
Vi_layer
Eq. (17.2) has been implemented.

Deltares 265 of 562

 Coupling to external models via Basic Model Interface (BMI)

Concentration
The exchanged concentration of, e.g., salinity in D-Flow FM is computed per layer in 3D
models. In case of a 2D model, it can be regarded as having only one layer.

DIMR runs the D-Flow FM and ZSF models in a number of update steps. At each update step,
the models run over an exchange interval, whose interval is configured in a DIMR configura-
tion file. It can happen that over an exchange interval, a D-Flow FM model runs over a number
of time steps. For each update process, D-Flow FM computes the input concentration for ZSF
as the average concentration over all grid cells in the lateral and over the exchange time inter-

T
val. The formula implemented in D-Flow FM for computing the average concentration at one
layer, denoted by ci_layer , reads:

P ncell
P
dtj · Vk · ck
j k
ci_layer = ,
AF T
ncell
P
k
Vk
(17.3)

where dtj is the j th computational time step during the update process, k is one cell on layer
i_layer, T is the exchange time interval, and Vk and ck are the volume and concentration
of cell k , respectively. The exchange time interval denotes the interval of communication be-
tween D-Flow FM and ZSF. Eq. (17.3) shows that values are accumulated over an exchange
time interval T before a concentration value is communicated towards the ZSF module.
DR

Deltares 266 of 562

18 Water quality and D-Flow FM

18.1 Introduction to the coupling of D-Flow FM to D-Water Quality

In the Delft3D Flexible Mesh Suite it is possible to use a D-Flow FM hydrodynamic model as
the basis for a D-Water Quality model in two distinct ways.

One way is to write the grid definition, the water balance and optionally other relevant data
like temparature fields and bottom shear stress to a set of files that can be used to set up a
D-Water Quality model afterwards. This is referred to as the file-based or offline coupling.1

T
This will be described in more detail in section 18.2.

Another way is to directly apply the processes in the D-Water Quality process library on trac-
ers that can be defined in D-Flow FM during a hydrodynamic calculation. This avoids writing
sometimes very big coupling files, and allows running D-Water Quality using MPI paralleli-
AF sation. This is referred to as the memory-based, or online coupling of hydrodynamics and
water quality, which will be described in more detail in section 18.3.

Note: The memory-based coupling is beta functionality, because currently this functionality
is not supported in the Delft3D-FM graphical user-interface. The user has to manual edit the
mdu-file and ext-file to set up the processes and their inputs.

In Table 18.1 an overview is presented of the most important pros and cons of both ap-
proaches.

Table 18.1: File-based versus memory-based D-Water Quality processes in D-Flow FM.
DR

Coupling Pros Cons

type
- run hydrodynamics only once
- possibly very large coupling files
File- - small models could be faster
based - complex models could become slower
- grid aggregation is possible
(offline)
- no coupling files needed - rerun hydrodynamics for each scenario
Memory- - no coupling mistakes - no aggregation possible
based - multi-node parallellism (via MPI) - no reuse of old water quality set-ups
(online)

A file-based coupling has several advantages. Hydrodynamic calculations can be time con-
suming, and one hydrodynamic data set can be used to run multiple water quality scenarios.
However, with the models becoming bigger and finer, the size of the coupling files is increas-
ing. Also since D-Water Quality has limited options for parallel computing, runs can become
very time-consuming. D-Water Quality only allows shared-memory parallellism and does not
allow distributed-memory parallellism via MPI. The latter was the main reason why the possi-
bility of using the D-Water Quality process library directly in D-Flow FM was implemented. This
coupling has been implemented in such a way that only the processes from D-Water Qual-
ity are used, using the exact same code as used in D-Water Quality. For each substance
that is defined in the water quality processes setup, a tracer is defined in D-Flow FM. The
advection-diffusion equations are solved by D-Flow FM as described in chapter 4: Concep-
1
The preferred, but imperfect terminology is file-based and memory-based coupling. We will use these terms
consistently in this chapter.

Deltares 267 of 562

 Water quality and D-Flow FM

tual description of transport equation, which can make use of MPI parallelism over multiple
nodes. The processes themselves do not need to make use of MPI parallelism, since the
processes do not interact horizontally, but only in the vertical direction (e.g. sedimentation,
light climate).

The memory-based coupling can also be beneficial for the storage requirements of simula-
tions, since in this coupling mode the data are already in memory. A downside of this method
is that when the user wants to evaluate different water quality configurations, for each simula-
tion not only the water quality simulation, but also the hydrodynamics needs to be recomputed.
This can imply recomputing the same hydrodynamic result for every water quality configura-

T
tion, which can become expensive.

Both approaches of coupling use the same processes library for water quality. The simulation
of substances, processes and their interactions is identical. The key difference is the compu-
tation of the transport of substances. In the file-based coupling, the transport is computed by
AF D-Water Quality, giving the user a range of integration options to use for the tranport equation
(see Deltares (2025i) for details). In the memory-based coupling, the transport is computed
by D-Flow FM, as described in chapter 4.

18.2 File-based (or offline) coupling of water quality and hydrodynamics

18.2.1 Introduction
D-Water Quality is the multi-dimensional water quality model framework developed by Deltares
over the past decades. It solves the advection-diffusion-reaction equation on a predefined
computational grid and for a wide range of model substances. D-Water Quality offers flexi-
DR

ble configuration of the substances to be included, as well as the processes to be evaluated.

D-Water Quality does not contain a hydrodynamic model, so model results on flow fields is ob-
tained from hydrodynamic models such as D-Flow FM 1D2D, D-Flow FM 2D3D or SOBEK 3.
Full documentation on the D-Water Quality module is available, see Deltares (2025i).

18.2.2 Creating output for D-Water Quality

Creating output for D-Water Quality by D-Flow FM can be enabled in the User Interface in
the main window under the tab ‘Output Parameters’. Change the “WAQ output interval” to
a nonzero value. The MDU-equivalent is the keyword [output], WaqInterval, where
three numbers can be put and they are in the order of “WAQinterval”, “WAQ output-start-
time”, “WAQ output-end-time”. Each number should be a whole number of seconds, and must
be a multiple of the “User time step” (see tab “Time frame”). Moreover, if the start and end
output time is not explicitly specified, they are automatically set to start and end time of the
simulation, respectively.

D-Flow FM will create a special output folder named <DFM_DELWAQ_mdu_name>. In this

folder a <∗.hyd>-file will be created that gives an overview of the coupling with references to
the files containing the hydrodynamic exchange data.

Load the <∗.hyd>-file in the D-Water Quality GUI to prepare the input for a water quality
calculation. For further information on how to run D-Water Quality please consult the relevant
user manual.

The D-Water Quality GUI fully supports coupling with results from D-Flow FM. Postprocessing
can be done in QUICKPLOT.

Deltares 268 of 562

 Water quality and D-Flow FM

18.2.3 Limitations and remarks

When using multiple partitions (as described in Chapter 8), D-Flow FM will create one <∗.hyd>-
file per partition in the special output folder. Since D-Water Quality can accept results for a
single partition only, you have to merge the results into one using a tool called waqmerge.

It can be useful to model the water quality processes on a coarser mesh than the hydrody-
namic grid, and for this grid aggregation would be useful. This can be done using the tools
D-WAQ DIDO and agrhyd.

T
These tools can be obtained by contacting Deltares support. The usage is described in the
DIDO manual and the D-Water Quality Tools manual.

18.3 Memory-based (or online) coupling of water quality and hydrodynamics

AF The memory-based coupling between D-Flow FM 2D3D and D-Water Quality has been tested
and used but is currently still β -functionality, and is not supported by the user interface. This
means the user has to manually edit the D-Flow FM input files to activate the processes. It is,
however, possible to add tracers in the user interface with the names of the D-Water Quality
substances to prepare e.g. boundary conditions. This section describes how to add the
processes from D-Water Quality to such a model.

Water quality modelling with D-Water Quality within D-Flow FM is very flexible. Substances,
water quality processes, output variables, etc. defined in the D-Water Quality processes li-
brary are all available in the memory-based coupling. The library can also be extended by
new processes via the open processes library mechanism. The basic steps in water quality
DR

modelling within D-Flow FM are:

1 Set up a hydrodynamic simulation.

2 Define the substances and water quality processes you want to include using PLCT.2
3 Refer to the sub-file you have created in the mdu-file, and optionally add a history output
file.
4 Choose a sensible processes time step (DtProcesses) and mass balance output interval
(MbaInterval) in the mdu-file.
5 Define initial conditions, boundary conditions for the substances in the ext-file.
6 Define constant and spatially or temporally varying process parameters in the ext-file.
7 Define mass balance areas in the ext-file.
8 Run the simulation.
9 Check the output.

18.3.1 Glossary of terms

As D-Flow FM uses the terms constituents and tracers and for the water quality processes
the term substances is added, this section gives a concise definition of these terms in order
to avoid confusion.

⋄ Substances are, in principle, subject to one or more water quality processes. For D-
Flow FM itself they are the same as tracers, if they are transported (also known as "active"
substances in D-Water Quality), otherwise they play no role in D-Flow FM itself. They are
defined via the sub-file.
⋄ Tracers are used in D-Flow FM to indicate transport due to flow and mixing. They do
not participate in the hydrodynamic equations, so there is no influence of tracers on the
hydrodynamics.
2
The abbreviation means "Processes Library Configuration Tool". It is a tool to construct sub-files.

Deltares 269 of 562

 Water quality and D-Flow FM

⋄ The term constituents is used for all (transported) quantities, including sediment (from D-
Morphology), salinity and temperature. The latter three do influence the hydrodynamics
via the density term and therefore play a more important role than tracers.

For example, when salinity, temperature or sediments are modelled via the D-Water Quality
model in D-Flow FM, as described in this chapter, then they do not influence the hydrodynam-
ics (via the density term) and are called substances. However, when salinity, temperature or
sediments are modelled in the hydrodynamic model of D-Flow FM, then they do influence the
hydrodynamics and are called constituents.

T
18.3.2 Definition of the water quality system
A water quality system is defined by the substances and the processes that influence these
substances. These processes can range from simple first-order decay (as with radio-active
AF substances) to complex interactions between a large number of substances, like with algal
growth.

The user can use all substances and processes that are available in D-Water Quality. A
comprehensive description of the formulations and the input and output items of the processes
can be found in Technical Reference Manual (Deltares, 2025h).

Processes can calculate actual fluxes between substances, but there are also ’informational’
processes that e.g. calculate the light climate or the total bottom shear stress or the total
resuspension flux. The setup, stored in a sub-file, can be created using.3 . For D-Water Qual-
ity, this sub-file is read by the user-interface, and the settings are incorporated in the D-
DR

Water Quality input file. D-Flow FM reads the sub-file directly.

The substance file is in plain text format, which allows manipulation by the user. The sub-
stance file contains:
⋄ a list of substances that are transported (active)
⋄ a list of substances that are not transported (inactive)
⋄ a list of constants and their values (see: Table 18.3.3)
⋄ a list of list of outputs (see: ref below)
⋄ a list of the processes that will be active

To use a sub-file, it has to be referred to in the mdu-file. Use the keyword [processes],
SubstanceFile.

Example of the reference to a sub-file in the mdu-file which will then activate the processes in
D-Flow FM:

[processes]
SubstanceFile = sed_3fraction.sub

Substances
There a two types of substances in D-Water Quality: active and inactive.
1 Active substances are added as tracers to the constituents of D-Flow FM. You can define
their initial conditions (or use the result from a previous run using a restart file), boundary
3
See the User Manual for the Deltares (2025g)

Deltares 270 of 562

 Water quality and D-Flow FM

conditions and sink-source concentrations in the same ways as for other constituents in
D-Flow FM.
2 Inactive substances usually reside only in the bottom water layer. They represent inorganic
sediments or organic material at the bottom, or rooting vegetation.

The non-transported substances are not part of the constituents in D-Flow FM. You can define
their initial conditions using a special keyword in the ext-file, or use the result from a previous
run using a restart file. You cannot define boundary conditions for them, since they are not
transported over boundaries. Also, you do not need to add concentrations for them when you

T
define sources and sinks. Then you only specify the transported constituents.

An actual list of the constituents in the model and their order is written to the diagnostics
file. This is useful, because this is the order in which the concentrations need to specified for
sources and sinks.
AF
Format for a substance definition in the sub-file:

substance <substance name> <active/inactive>

description <decription>
concentration-unit <unit>
waste-load-unit <waste load unit>
end-substance

Example of substance definitions in a sub-file:

DR

substance 'IM1' active

description 'inorganic matter (IM1)'
concentration-unit '(gDM/m3)'
waste-load-unit '-'
end-substance
substance 'IM1S1' inactive
description 'IM1 in layer S1'
concentration-unit '(gDM/m2)'
waste-load-unit '-'
end-substance

Processes
The processes in the D-Water Quality processes library cover a large number of water quality
problems. An overview can be seen in Figure 18.1. The user can select which processes are
relevant and switched on. D-Flow FM will evaluate if all required input is available to actually
calculate the processes. A report of this will be available in the lsp-report file. Also check this
file for warnings amd errors messages that are specific for D-Water Quality.

All processes from D-Water Quality can be used in D-Flow FM. Processes are often evalu-
ated at larger time steps than the hydrodynamics and transport using fractional stepping. A
time step, DtProcesses, for the evaluation of processes must be set in the mdu-file. The
processes are evaluated at this interval, which leads to fluxes. The effect is directly applied
to the concentration field, after which the transport continues without any further interaction
between the substances until the next water quality time step.

Limitation: DtProcesses must be a multiple of the dtuser, and can be specified in the
processes section of the mdu-file using the MDU keyword [processes], DtProcesses.
If DtProcesses is negative, water quality processes are calculated at every hydrodynamic
time step. A list of the processes to be switched on is given in the sub-file.

Deltares 271 of 562

 Water quality and D-Flow FM

Atmosphere
Water
Methane DissolvedMOxygen OxygenMDemand
BOD COD

Continuity pH Phytoplankton Grazers InorganicMMatter HeavyMMetals

TIC Alkalinity C N P Si S C N P Si IMF IME IM/ As Cd Cr Cu Hg
Salinity-Chloride Ni Pb V Zn

Temperature
Nutrients OrganicMMatter OrganicMMatter OrganicMmicroB
NO/ NH5 PO5 Si zparticulatex zdissolvedx pollutants
Conservative POC PON POP POS DOC DON DOP DOS Atr BaP Diu Flu
Tracers AAP VIVP APATP OPAL
HCB HCH PCB OMP
5MComponents

T
Decayable Iron Sulphur
Tracers
7MComponents SO5 SUD SUP
5MComponents

Bacteria
EnCoc EColi FColi TColi

Sediment
SedimentMOxygen Nutrients OrganicMMatter OrganicMMatter InorganicMMatter HeavyMMetals
Demand zparticulatex zdissolvedx
AF C
MicroB
phytobentos
N P Si
Oxygen

Sulphur

Iron
POC PON POP POS

Methane
DOC DON DOP DOS
IMF IME IM/
OrganicMmicroB
pollutants

Figure 18.1: General overview of substances included in D-Water Quality. Substances

are organised in functional groups indicated by a grey header, except for
some substances that form a group of their own. Major links between sub-
stances are indicated by arrows; note that many links are omitted.

Example of a processes time step definition in the mdu-file:

DR

[processes]
DtProcesses = 600.0

Format for a processes list in the sub-file:

active-processes
name <name 1> <decription 1>
name <name 2> <decription 2>
:
name <name n> <decription n>
end-active-processes

Example of a processes list in the sub-file

active-processes
name 'Compos' 'Composition'
name 'Nitrif_NH4' 'Nitrification of ammonium'
name 'DecFast' 'Mineralization fast decomp. detritus POC1'
:
name 'Daylength' 'Daylength calculation'
end-active-processes

18.3.3 Definition of process parameters

In D-Water Quality there are four types of process parameters, constant in time and space,
varying in time, varying in space, and varying in both time and space. In Table 18.2, you can

Deltares 272 of 562

 Water quality and D-Flow FM

see an overview of these types, with the D-Water Quality term for them in italics, and the way
they can be specified in D-Flow FM.

Table 18.2: Various types of parameter inputs for water quality models in D-Flow FM.

Constant in time Varying in time

constant function
Constant in space define a parameter define a waqfunction
in the sub-file in the ext-file

T
parameter segment function
Varying in space define a waqparameter define a waqsegmentfunction
in the ext-file in the ext-file
AF
Constant parameter input
Process parameters that remain constant during the calculation are called constant in D-
Water Quality, and are specified in the sub-file when using D-Water Quality within D-Flow FM.
A constant value in the substance file can however be replaced by a spatial or temporal
definition in the ext-file.

Format for a constant definition in the sub-file:

parameter <parameter name>

DR

description <decription>
unit <unit>
value <value>
end-substance

Two examples of a constant definition in the sub-file:

parameter 'V0SedIM1'
description 'sedimentation velocity IM1'
unit '(m/d)'
value 7.20000E-00
end-parameter
parameter 'TaucRS1DM'
description 'critical shear stress for resuspension DM layer S1'
unit '(N/m2)'
value 0.2000E+00
end-parameter

Spatial parameter input

Spatially varying input for a process parameter is called a parameter in D-Water Quality. In
D-Flow FM, these are defined in the ext-file using QUANTITY=waqparameter<name>. At
the moment, data can only be specified in 2D, and this information is copied to all layers.

QUANTITY=waqparameterV0SedIM1
FILENAME=para1.pol
FILETYPE=10
METHOD=4
OPERAND=O

Deltares 273 of 562

 Water quality and D-Flow FM

VALUE=3.6

QUANTITY=waqparameterV0SedIM1
FILENAME=para2.pol
FILETYPE=10
METHOD=4
OPERAND=O
VALUE=7.2

Temporal parameter input

T
Temporal varying input for a process parameter is called a function in D-Water Quality. In
D-Flow FM, these are defined in the ext-file using QUANTITY=waqfunction<name>.

QUANTITY=waqfunctionV0SedIM1
FILENAME =V0SedIM1.tim*
AF
FILETYPE =1
METHOD =1**
OPERAND =O

QUANTITY=waqfunctionV0SedIM2
FILENAME =V0SedIM2.fun*
FILETYPE =1
METHOD =0**
OPERAND =O

* file containing a time series for this parameter;

** method: 0 = block, 1 = linear interpolation
DR

Spatial and temporal parameter input

Parameter input data that are both spatial and temporal varying are referred to as a segment
function in D-Water Quality. In a memory-based combined model, you can specify external
data sources, but also connect to hydrodynamic and meteorological data that are already
available within D-Flow FM in your model.

Defining external data sources for segment functions

In D-Flow FM, you can specify segment functions in the ext-file using
QUANTITY=waqsegmentfunction<name>. At the moment, only data specified on a
curvilinear grid in a netCDF are supported (filetype=11, section E.2.4). We hope to support
temporal varying sample files in the near future. Data can only be specified in 2D, and the
information is copied to all layers.

QUANTITY=waqsegmentfunctionIM1
FILENAME=f34_sediments.nc
VARNAME=IM1
FILETYPE=11
METHOD=3
OPERAND=O

Making parameters from D-Flow FM available for processes

Within D-Flow FM it is possible to connect several parameters to the water quality processes.
If you mention the name of certain parameters in the sub-file, they will be replaced by data
from D-Flow FM, when available. Table 18.3 shows which data can be connected by which
parameters. Which data are actually connected is reported in the dia-file.

Deltares 274 of 562

 Water quality and D-Flow FM

Table 18.3: Data from D-Flow FM that are available for water quality processes

D-Flow FM data D-Water Quality name in sub-file

horizontal surface area Surf (default)
bottom shear stress Tau or TauFlow*
flow element center velocity Velocity
salinity Salinity
temperature Temp

T
wind velocity magnitude VWind
wind direction WindDir
fetch length and fetch depth Fetch and/or InitDepth**
solar radiation RadSurf
AF rain (mm/day)
wave height
Rain (mm/h)
WaveHeight
wave length WaveLength
wave period WavePeriod
*The bottom shear stress can be connected to Tau or TauFlow. When you connect to Tau-
Flow, you can use the process CalTau to calculate a Tau for the water quality processes
with an additional bottom shear stress. Please be aware that if the D-Flow FM switch
jawaveSwartDelwaq has been set to anything other than zero or D-Waves is coupled,
there is already wave bottom shear stress included in TauFlow. Adding extra wave bottom
DR

shear stress with CalTau would lead to a doubling of wave bottom shear stress.
**Fetch length and fetch depth are both connected when either Fetch and/or InitDepth is
mentioned in the sub-file.

These are predefined quantities but defining them in the sub-file makes them "visible" in the
processes library. If do not want to use the data available from D-Flow FM but want to specify
your own input, you must not define the quantity as a process parameter in the sub-file, but
add it as spatial and/or temporal input in the ext-file. If you just want to use a constant value,
a uniform time series (18.3.3) with the same value for the beginning and the end of your
calculation period.

18.3.4 Initial conditions, boundary conditions and sources and sinks

Most substances in the model will have certain initial conditions, boundary conditions and
sources and sinks (the equivalent of D-Water Quality waste loads). A D-Flow FM and D-
Water Quality model that is memory-based makes uses of D-Flow FM tracers, therefore you
have to make use of the D-Flow FM methods to prescribe them (See also: section 4.3). The
options will be briefly discussed here.

Deltares 275 of 562

 Water quality and D-Flow FM

Initial condition
The initial conditions for transported water quality substances are handled in exactly the same
manner as those for any other constituents, i.e. you can specify a horizontally spatially varying
field in the usual way through the ext-file using QUANTITY=initialtracer<name>.

For non-transported water quality substances use QUANTITY=initialwaqbot<name>.

You can also refer to a restart file in the mdu-file. Restart conditions are read from the restart
file by substance name, not by order in the file, and can contain both transported and non-

T
transported substances.

QUANTITY=initialtracerIM1
FILENAME=initracer.pol
FILETYPE=10
METHOD=4
AF
OPERAND=O
VALUE=5.0

QUANTITY=initialwaqbotIM1S1
FILENAME=initracer.pol
FILETYPE=10
METHOD=4
OPERAND=O
VALUE=100.0

Boundary conditions
All of the D-Flow FM options for tracers and other constituents are also available for trans-
DR

ported water quality substances. You can specify boundary conditions for all these substances
at all open inflow boundaries in the ext-file using QUANTITY=tracerbnd<name>. When
modelling in three dimensions you may choose to specify boundary concentrations that have
a uniform, linear, or step distribution over the vertical. You may also choose to specify a
“Thatcher-Harleman” return time to simulate the re-entry of material that flowed out of the
model after the flow reverses direction. Note that when no boundary concentration is pre-
scribed, the concentration is presumed to be equal to the current concentration of the en-
trance cell of the model. This is different from running a file-based D-Water Quality model,
where missing concentrations are presumed to be zero.

QUANTITY=tracerbndIM1
FILENAME=leftIM1_sed.pli*
FILETYPE=9
METHOD=3
OPERAND=O

QUANTITY=tracerbndIM2
FILENAME=leftIM2_sed.pli*
FILETYPE=9
METHOD=3
OPERAND=O

* a tim-file (time series) with the same name is read

Sources and sinks

Sources and sinks are the equivalent of waste loads in D-Water Quality. They may be provided
using using QUANTITY=discharge_salinity_temperature_sorsin in the ext-file
as follows:

Deltares 276 of 562

 Water quality and D-Flow FM

QUANTITY=discharge_salinity_temperature_sorsin
FILENAME =WWTP.pliz*
FILETYPE =9
METHOD =3
OPERAND =O
AREA =0

* a tim-file (time series) with the same name is read

T
The tim-file simultaneously prescribes sources and sinks of
⋄ water volume itself (i.e. discharge),
⋄ salinity (when switched on in the model), and
⋄ temperature (when switched on in the model), and.
⋄ any other constituents that are transported.
AF
See section 7.4.11 for more details.

The number of columns in the time file is equal to 2 (time and discharge) + 0/1/2 (depending
on whether salinity and/or temperate are switched on) + <the number of constituents>. The
diagnostic file contains a list of the actual order of the constituents. The non-transported
substances are not part of the constituents, and do not have values in the tim-file.

Warning:
Be aware that the order in which you specify boundary conditions, initial conditions in the ext-
DR

file and the substances in the sub-file influences the order of the constituents in the tim-file.
This can lead to another interpretation of the tim-file than you would have expected – the
columns in the tim file cannot be labelled with names.

Warning:
Another, somewhat subtler, aspect of the current set-up of sources and sinks is that all data
in the tim-file are interpolated linearly, so that the resulting waste load is quadratically depen-
dent on time, rather than linearly. With large time steps between records in the tim-file and
rapidly changes discharge rates and concentrations this may cause noticeable discrepancies
between the mass you expect and what is actually put into the model. The easiest solution
is probably to use block-wise constant concentrations and let the discharge rate vary linearly,
for example (assuming a single substance and no salinity or temperature in the model):

1000.0 10.0 1.0

2000.0 20.0 1.0
2001.0 20.0 0.0 <-- Extra record to make the transition
3000.0 20.0 0.0
4000.0 20.0 0.0
4001.0 20.0 1.0 <-- Ditto
5000.0 10.0 1.0

Because D-Flow FM is a hydrodynamic model, the water discharge is always added to the
model. Dry waste loads are not possible yet, but a workaround might be that you divided the
discharges by a factor 1000 or 106 , and multiply the concentrations by the same factor.

Deltares 277 of 562

 Water quality and D-Flow FM

18.3.5 Special options

There are some special options for memory-based D-Flow FM and D-Water Quality models.
The options will be briefly discussed here.

Handeling of dry segments

When cells contain a limited amount of water, or no water at all, some processes can behave
peculiarly, and cause negative concentrations or instabilities. To prevent this, processes re-
ceive a signal when segments are dry. Several processes consciously ignore the dry label

T
and will always do calculations in dry cells because they deal with it properly, or e.g. are for
processes in the sediment that continue in dry cells.

By default, segments are considered dry when the volume drops below 0.001m3 or the depth
of the layer drops below 0.001m. The same defaults are used in D-Water Quality. The user
AF can adjust these settings by using the following keywords in the [processes] section of
the mdu-file:

[processes]
VolumeDryThreshold = 1.0e-3
DepthDryThreshold = 1.0e-3

Partial deactivation of processes

It is possible to switch off all processes in parts of your model. You can specify this through the
DR

ext-file using QUANTITY=waqparameterProcessesInactive using a polygon. Pro-

cesses will not be evaluated for that region.

QUANTITY=waqparameterProcessesInactive
FILENAME=InactiveArea.pol
FILETYPE=10
METHOD=4
OPERAND=O
VALUE=1.0

Segment number conversion

Specifically for the D-Water Quality process of dredging and dumping of sediments, the user
has to specify a segment or cell numbers for the dumping location. In parallel runs, this
number has to be converted to a local segment number. You can specify these global segment
numbers in the ext-file using QUANTITY=waqsegmentnumber<name>.

QUANTITY=waqsegmentnumberseg___dr01
FILENAME=wholemodel.pol
FILETYPE=10
METHOD=4
OPERAND=O
VALUE=3472

18.3.6 Output options

Deltares 278 of 562

 Water quality and D-Flow FM

Map and history output

All output parameters defined in the sub-file are written to both the map-output and his-output
of D-Flow FM. This might not always be desirable. To distinguish between map and his-
tory output, it is possible to move a selection of outputs from the sub-file to a separate
file that must be mentioned in the mdu-file. The map-file will only contain outputs defined
in the sub-file. The his-file will contain all outputs mentioned in both the sub-file and the
AdditionalHistoryOutputFile. Use the keyword [processes],
AdditionalHistoryOutputFile.

T
Example of this setting in the mdu-file:

[processes]
AdditionalHistoryOutputFile = addhisout.eho
AF
Format for an output definition in the sub-file or eho-file:

output <output name>

description <decription>
end-output

Example of the output definition in the sub-file or eho-file:

DR

output 'Tau'
description 'total bottom shear stress'
end-output
output 'Surf'
description 'Horizontal surface'
end-output
output 'TotalDepth'
description 'Total depth of water column'
end-output

Mass balance areas

Define mass balance areas using polygons with QUANTITY=massbalancearea<name>
in the ext-file4 . If there is any overlap in the polygons when using multiple mass balance
areas, the last definition will overrule any previous definitions. If there are cells remaining that
are not included in any mass balance area, they will be grouped in an extra mass balance
area named Remaining cells. This will cut up the whole model area in non-overlapping mass
balance areas. The extreme form of this is by not specifying any mass balance area in which
case all cells will end up in the remaining area, and you effectively get the mass balance for
the whole model.

D-Flow FM will produce mass balances for the defined areas, which gives an overview of
the fluxes between the various mass balance areas, over the model boundaries, and the
process fluxes in each mass balance area. The mass balances will be written to text and
binary files at a given interval, and at the end of the run. Use the MDU keyword [output],
MbaInterval to set the interval5 .

4
This used to be QUANTITY=waqmassbalancearea<name>.
5
This used to be [processes], DtMassBalance

Deltares 279 of 562

 Water quality and D-Flow FM

Note: MbaInterval must be a multiple of the dtuser.

It is possible to group four groups of terms in the output for the mass balance areas: Exchange
between the areas, exchange over boundaries, source/sinks and process fluxes. This will
reduce the output in case you are not interested in all details. Use the following mdu-keyword
in the [output] section with (1: yes, 0: no):
⋄ MbaLumpFromToMba to lump the from/to other areas
⋄ MbaLumpBoundaries to lump the boundaries
⋄ MbaLumpSourceSinks to lump the source/sinks
⋄

T
MbaLumpProcesses to lump the processes

By default, the mass balance areas output is written to a text file. However, there are also
some other options that are easier to process in post-processing tools which can be switched
on/off by means of the following keywords in the [output] section (1: yes, 0: no):
AF
⋄ MbaWriteTxt to write to a text file containing one formatted balance table per mass
balance area, per mass balance quantity, and per mass balance period (default: yes)
⋄ MbaWriteCsv to write to two csv-files: one file with the initial and final volumes/masses
of all mass balance areas for all quantities for all periods, and one file with the fluxes of all
areas, for all quantities and all periods (default: no)
⋄ MbaWriteNetCDF to write to netCDF-file containing all fluxes per quantity per period
per area (default: no) This output format is supported by QUICKPLOT.

Example of this setting in the mdu-file:

DR

[output]
MbaInterval = 86400.0
MbaLumpFromToMba = 0
MbaLumpBoundaries = 0
MbaLumpSourceSinks = 1
MbaLumpProcesses = 0
MbaWriteTxt = 1
MbaWriteCsv = 1
MbaWriteNetCDF = 0

Example of the mass balance area definition in the ext-file.

QUANTITY=massbalanceareaBalArea1
FILENAME=barea1.pol
FILETYPE=10
METHOD=4
OPERAND=O
VALUE=1.0*

QUANTITY=massbalanceareaBalArea2
FILENAME=barea2.pol
FILETYPE=10
METHOD=4
OPERAND=O
VALUE=1.0*

*Ignored

Deltares 280 of 562

 Water quality and D-Flow FM

Statistical output
It is possible to have statistical output in a memory-based run, similar to standalone D-
Water Quality. You can specify an stt-file in the same format as used in D-Water Quality.
Use the MDU keyword [processes], StatisticsFile to provide the name. For a de-
scription of the stt-file please refer to chapter 10 of the D-Water Quality Input File Manual
(Deltares, 2025f).

18.3.7 Running D-Flow FM with processes

T
When running D-Flow FM with processes, it needs to read a processes data base that con-
tains input/output information of all the processes. The processes database is closely related
to the code in the executable, and generally it is advised to use the process library that comes
with the D-Flow FM executable. Using the open processes library that uses additional sub-
routines in a separate dll-file (Windows) or so-file (Linux) is also supported. When using the
AF BLOOM algae model, D-Flow FM also needs to read a BLOOM algae species file. All these
options must be given as command-line arguments in the following way:

> dflowfm-cli <mdu-file> --autostartstop --processlibrary <proc_def>

--openprocessdllso <openprocessess dll/so> --bloomspecies <bloom.spe>

--processlibrary PROCESSLIBRARYFILE
Specify the process library file to be used for water quality processes.

--openprocessdllso OPENPROCESSDLLSOFILE
DR

Specify the open process dll/so file with additional subroutines to be

used for water quality processes.

--bloomspecies BLOOMSPECIESFILE
Specify the BLOOM species definition file to be used for water quality
processes.

18.3.8 Output
The water quality output can be found in the D-Flow FM map and history files according to the
user specifications (see: section 18.3.6).

The output for the mass balance areas is written into two text files named after the mdu-file,
and appended with ’_bal.txt’ and ’_baltot.txt’. They contain an overview of the mass balance
areas, the active an inactive substances and the fluxes that affect the substances and their
stoichiometry factor. It is also possible to write the mass balances to a NetCDF-file, and
inspect them using QUICKPLOT.

What follows for each mass balance area (and for each mass balance interval in the case of
the _bal.txt-file), is a water and mass balance for each substance, followed by a water and
mass balance for each substance for the whole area.

18.3.9 Known issues and limitations

The processes functionality has the following limitations:
⋄ Although the sinks and source are working for constituents and thus water quality sub-
stances, it is a bit difficult to add concentrations to these sinks and sources. In the tim-file
that accompanies the sinks en sources, besides the discharge the user has to specify the
concentrations of constituents in unnamed columns. But the order is determined by the

Deltares 281 of 562

 Water quality and D-Flow FM

order that constituents are defined in first the ext-file and then the sub-file (for substances
that have no initial conditions or boundaries. Adding a substance means you’ll immedi-
ately have to fix the tim-file. The dia-file now contains an actual list of the order of the
constituents.
⋄ Tim files are using time in minutes since reference date. It is not yet possible to use
absolute dates.

18.4 Particle tracking

Note:

T
Modelling of particle tracks is currently either internal β -functionality (2D) or pre-α-functionality
(3D) in D-Flow FM. Currently, the DELFT3D-PART module is extended so that hydrodynamic
model results on both structured grids and unstructured grids can be applied for particle track-
ing. This is currently α-functionality and is therefore not available yet.
AF
DR

Deltares 282 of 562

19 Morphology
Modelling of morphology is described in a separate User Manual; see (Deltares, 2025d).

T
AF
DR

Deltares 283 of 562

20 Coupling with Nearfield data via COSUMO
D-Flow FM can be coupled to the external program called COSUMO, created by Deltares,
for modelling subgrid processes. A typical example is a discharge via a diffuser. D-Flow FM
delivers ambient data to COSUMO (flow velocities, concentrations) and COSUMO delivers
discharge data to D-Flow FM. Contact Deltares for more information.

Restriction:
⋄ When D-Flow FM runs integrated with COSUMO, D-Flow FM can not run in parallel yet.

T
20.1 Getting started
When D-Flow FM is coupled with COSUMO, DIMR must be used to run a simulation, manag-
ing the following two dlls/so’s:
AF ⋄ D-Flow FM as a dll, named <dflowfm.dll>
⋄ <cosumo_bmi.dll> which takes care of the communication with a running COSUMO in-
stance

The following files are involved:

⋄ <dimr_config.xml>, see section 20.1.2. This file connects D-Flow FM to cosumo_bmi
and specifies the quantities to be exchanged between them.
⋄ <COSUMOsettings.xml>, see section 20.1.3, configures COSUMO and is identical to
the one used in Delft3D-FLOW.
DR

⋄ <FF2NF.xml>, see section 20.1.4, contains FarFieldToNearField data, is created on the

fly by cosumo_bmi, is read by COSUMO and is identical to the one used in Delft3D-FLOW.
⋄ <NF2FF.xml>, see section 20.1.5, contains NearFieldToFarField data, is created on the
fly by COSUMO, is read by cosumo_bmi and is identical to the one used in Delft3D-FLOW.

The mdu-file may contain the following additional, optional keywords:

Keyword Value Description Default

NFEntrainmentMomentum 1I In block [physics], 1: Momen- 0

tum transfer in NearField re-
lated entrainment
Wrimap_NearField 1I In block [output], write near 0
field parameters (1: yes, 0:
no)

Deltares 284 of 562

 Coupling with Nearfield data via COSUMO

20.1.1 Run procedure

Obtain the COSUMO program from Deltares. Currently, only a Windows version is available.
The exchange between COSUMO and D-Flow FM is via files. If D-Flow FM runs on Linux, a
file system is needed that supports both reading/writing on Linux and on Windows.

A typical COSUMO instance checks a specified folder, e.g. FF2NF (FarFieldToNearField),

for files to appear, placed there by cosumo_bmi (using data from D-Flow FM, obtained via
DIMR), to be processed by COSUMO. When COSUMO has processed the FF2NF-file, it
will produce a NF2FF-file. COSUMO will place this resulting file in a folder, e.g. NF2FF

T
(NearFieldToFarField). cosumo_bmi checks this NF2FF-folder for files to appear. When they
do, cosumo_bmi will read these files, transfer data to D-Flow FM via DIMR and the D-Flow FM
computation will continue with updated data.

One COSUMO instance can serve multiple D-Flow FM computations at the same time. To
distinct these files, D-Flow FM adds a uniqueId to the name of the file, consisting of two
AF underscores with 6 capital letters, e.g. "_WGUPKA_". COSUMO will add this uniqueId also
to the name of the resulting NF2FF-file.

When starting a simulation, be sure that COSUMO is running as a service. Then start DIMR,
using a correct dimr_config file, referring to a correct COSUMO settings file.

Examples are available upon request.

20.1.2 Input DIMR

Both D-Flow FM and COSUMO are used as dynamic libraries (DLL’s on Windows, so’s on
DR

Linux). DIMR is a small executable steering both dynamic libraries. Its input file, usually
called “dimr_config.xml”, looks like this when combining D-Flow FM with COSUMO:
<?xml version="1.0" encoding="iso-8859-1"?>
<dimrConfig xmlns="http://schemas.deltares.nl/dimr"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.deltares.nl/dimr
http://content.oss.deltares.nl/schemas/dimr-1.0.xsd">
<documentation>
<fileVersion>1.00</fileVersion>
<createdBy>Deltares, Coupling team</createdBy>
<creationDate>2015-05-20T07:56:32+01:00</creationDate>
</documentation>

<control>
<parallel>
<startGroup>
<time>0 1800 21600</time>
<coupler name="flow2cosumo"/>
<start name="COSUMO"/>
<coupler name="cosumo2flow"/>
</startGroup>
<start name="FM"/>
</parallel>
</control>

<component name="FM">
<library>dflowfm</library>
<workingDir>fm</workingDir>
<inputFile>FlowFM.mdu</inputFile>
</component>

<component name="COSUMO">
<library>cosumo_bmi</library>

Deltares 285 of 562

 Coupling with Nearfield data via COSUMO

<workingDir>cosumo</workingDir>
<inputFile>COSUMOsettings.xml</inputFile>
<parameter key="skipUniqueID" value="yes"/>
</component>

<coupler name="flow2cosumo">
<sourceComponent>FM</sourceComponent>
<targetComponent>COSUMO</targetComponent>
<item type="pointer">
<sourceName>geometry/xcc</sourceName>
<targetName>flow_xcc</targetName>
</item>

T
<item type="pointer">
<sourceName>geometry/ycc</sourceName>
<targetName>flow_ycc</targetName>
</item>
<item type="pointer">
<sourceName>geometry/z_level</sourceName>
<targetName>z_level_cc</targetName>
AF </item>
<item type="pointer">
<sourceName>geometry/kbot</sourceName>
<targetName>kbot</targetName>
</item>
<item type="pointer">
<sourceName>geometry/ktop</sourceName>
<targetName>ktop</targetName>
</item>
<item type="pointer">
<sourceName>field/water_depth</sourceName>
<targetName>water_depth_cc</targetName>
</item>
DR

<item type="pointer">
<sourceName>field/velocity_x</sourceName>
<targetName>velocity_x_cc</targetName>
</item>
<item type="pointer">
<sourceName>field/velocity_y</sourceName>
<targetName>velocity_y_cc</targetName>
</item>
<item type="pointer">
<sourceName>field/rho</sourceName>
<targetName>rho_cc</targetName>
</item>
<item type="pointer">
<sourceName>field/constituents</sourceName>
<targetName>constituents</targetName>
</item>
<item>
<sourceName>isalt</sourceName>
<targetName>isalt</targetName>
</item>
<item>
<sourceName>itemp</sourceName>
<targetName>itemp</targetName>
</item>
<item type="pointer">
<sourceName>runid</sourceName>
<targetName>runid</targetName>
</item>
<item type="pointer">
<sourceName>constituents_names</sourceName>
<targetName>constituents_names</targetName>
</item>
</coupler>

Deltares 286 of 562

 Coupling with Nearfield data via COSUMO

<coupler name="cosumo2flow">
<sourceComponent>COSUMO</sourceComponent>
<targetComponent>FM</targetComponent>
<item type="pointer">
<sourceName>nf_q_source</sourceName>
<targetName>sourcesinks/COSUMO/nf_q_source</targetName>
</item>
<item type="pointer">
<sourceName>nf_q_intake</sourceName>
<targetName>sourcesinks/COSUMO/nf_q_intake</targetName>
</item>
<item type="pointer">

T
<sourceName>nf_const</sourceName>
<targetName>sourcesinks/COSUMO/nf_const</targetName>
</item>
<item type="pointer">
<sourceName>nf_intake</sourceName>
<targetName>sourcesinks/COSUMO/nf_intake</targetName>
AF </item>
<item type="pointer">
<sourceName>nf_sink</sourceName>
<targetName>sourcesinks/COSUMO/nf_sink</targetName>
</item>
<item type="pointer">
<sourceName>nf_sour</sourceName>
<targetName>sourcesinks/COSUMO/nf_sour</targetName>
</item>
<item type="pointer">
<sourceName>nf_const_operator</sourceName>
<targetName>sourcesinks/COSUMO/nf_const_operator</targetName>
</item>
DR

<item type="pointer">
<sourceName>nf_src_mom</sourceName>
<targetName>sourcesinks/COSUMO/nf_src_mom</targetName>
</item>
<logger>
<workingDir>.</workingDir>
<outputFile>cosumo_to_dflowfm.nc</outputFile>
</logger>
</coupler>
</dimrConfig>

Description:
<control> Specifies the workflow of the deltaresHydro executable. It indicates which com-
ponents are started in which order. If the data transfer is to be arranged by
the main program DIMR, then a coupler should be included. The main <con-
trol> block is a sequential block; this means that each component is initialized,
time stepped, and finalized before the next component starts. For each com-
ponent/coupler listed inside the <control> block there will be a corresponding
component/coupler specification block defined below.
<parallel> Within a <parallel> tag the components are started concurrently (if the mpi pro-
cess id’s listed per component don’t overlap) or executed synchronously in se-
quence (first all initialize, then time stepping, and to conclude all finalization
calls). The order of the components is retained.
<start> A <parallel> block contains exactly one <start> component, defining the start
and end time of the simulation. This is the component inside the <parallel> block
with the smallest time step and can be denoted as the ”master-component”. All
other components must be defined with a <startGroup> and can be denoted as
a ”slave-component”.
<startGroup> A <startGroup> should be used if a component (possibly including couplers)
should only be executed at a subset of simulation time steps.

Deltares 287 of 562

 Coupling with Nearfield data via COSUMO

<time> Start-, step- and stop-time (in seconds) at which this slave-component should
be executed. The times are relative to the times of the master-component. Thus
a start-time of 0.0 always refers to the start time of the master-component and
a stop-time of ”infinity” always refers to the end time of the master-component.
<component name="myComponentName"> Component specification block. ”myCompo-
nentName” is free to be defined by the user. It must match exactly with the
reference in the <control> block above. The name of a component must be
unique.
<library> Reference to the component to be executed. Currently ”flowfm”, ”wave” and
”FBCTools_BMI” are supported. The name must match exactly the name of

T
the related dll/so (excluding prefixes (e.g. “lib”) and suffixes (e.g. “.dll” or “.so”)).
The library should be located in the search path, or it may include an absolute or
relative path. Multiple <component> blocks may refer to the same component
to be executed.
<process> Optional list of the ids of the mpi processes that should be used to run the
AF component. If not specified, then the component will run only in process “0”
(i.e. non-parallel). The processes may be specified as a space separated list
with series compressed using colons e.g. “16:31” represents processes “16 17
18” up to “31”.
<mpiCommunicator> D-Flow FM specific flag. Mandatory only when this D-Flow FM com-
ponent should run a parallel (partitioned) model. Note that this is unrelated to
the <parallel> tag as introduced above.
<workingDir> Specification of the working directory of this <component>, relative to the
location of the “dimr_config.xml” file. The workingDir is the base/root directory
of all input and output files for the component. All other files will be located
RELATIVE TO this folder. If not specified, then workingDir will be equal to the
DR

folder of the configuration file.

<inputFile> Specification of the input file of this <component>, relative to <workingDir>:
D-Flow FM: mdu-file, D-Waves: mdw-file, D-RTC: .
<coupler name="myCouplerName"> Coupler specification block. ”myCouplerName” is free
to be defined by the user. It must match exactly with the reference in the <con-
trol> block above. The name of a coupler must be unique.
<sourceComponent> Identifies which component provides the data.
<targetComponent> Identifies which component needs to receive the data. The coupler
runs on the superset of the processes configured for the source and target
components.
<item> For each quantity to be exchanged, the name in the source component and the
name in the target component are specified. To support recursive components,
a directory syntax is used with forward slashes. If a name includes a forward
slash, then it needs to be escaped using a backward slash, like \/; if a name
includes a backward slash, then it needs to be escaped with a backward slash,
like \\.
<sourceName> Identifies which parameter will be sent at the source component side.
<targetName> Identifies which parameter will be received at the target component side.
<parameter> DIMR way to provide parameters in the form of key - value pairs. For the
COSUMO coupling, only the key skipUniqueID is relevant.

Deltares 288 of 562

 Coupling with Nearfield data via COSUMO

20.1.3 COSUMO config file

Below is an example <COSUMOsettings.xml>.

Remarks:
⋄ Multiple diffusors can be specified in one file.
⋄ Tag "<FF2NFdir>" specifies the folder where cosumo_bmi will put the FarFieldToN-
earField file. COOSUMO will monitor that folder, waiting for a file to be processed.
COSUMO will generate a NearFieldToFarField file and put it in the neighbouring folder
named "NF2FF".
⋄ See COSUMO manual for more details.

T
<?xml version="1.0" encoding="utf-8"?>
<COSUMO>
<fileVersion>0.3</fileVersion>
<settings>
<general>
AF <subGridModel>cormix</subGridModel>
<ID>Diffusor_1</ID>
<farFieldModel>Delft3D</farFieldModel>
<preProcessFcn></preProcessFcn>
<postProcessFcn>postProcessFcn_coupleAtVerticalMixingSpreadSinks</postProcessFcn>
<cmxFile>/path/to/cormix_file.cmx</cmxFile>
</general>
<comm>
<FF2NFdir>COSUMO\FF2NF\</FF2NFdir>
<FFrundir>rundir</FFrundir>
</comm>
<data>
<XYdiff>550.0 350.0</XYdiff>
<XYambient>823.0 344.8</XYambient>
DR

<XYambient>465.8 793.2</XYambient>
<XYambient>587.4 509.2</XYambient>
<XYintake>567.0 821.3453</XYintake>
<discharge>
<M3s>10.0</M3s>
Operator: "absolute" values or "excess" (dT,dS,d..) -->
<constituentsOperator>excess</constituentsOperator>
<constituents>10.0 0.0 0.0</constituents>
</discharge>
<D0>2.5</D0>
<H0>3.2</H0>
<Theta0>15.0</Theta0>
<Sigma0>0.0</Sigma0>
</data>
</settings>
<settings>
<general>
<subGridModel>cormix</subGridModel>
<ID>Diffusor_3</ID>
<farFieldModel>Delft3D</farFieldModel>
<preProcessFcn></preProcessFcn>
<postProcessFcn>postProcessFcn_coupleAtVerticalMixingSpreadSinks</postProcessFcn>
<cmxFile>/path/to/cormix_file.cmx</cmxFile>
</general>
<comm>
<FF2NFdir>COSUMO\FF2NF\</FF2NFdir>
<FFrundir>rundir</FFrundir>
</comm>
<data>
<XYdiff>1350.0 850.0</XYdiff>
<XYambient>1689.34 832.789</XYambient>
<XYambient>1308.27 712.603</XYambient>
<XYintake>1365.65 349.8342</XYintake>
<discharge>

Deltares 289 of 562

 Coupling with Nearfield data via COSUMO

<M3s>10.0</M3s>
Operator: "absolute" values or "excess" (dT,dS,d..) -->
<constituentsOperator>excess</constituentsOperator>
<constituents>10.0 0.0 0.0</constituents>
</discharge>
<D0>2.5</D0>
<H0>3.2</H0>
<Theta0>15.0</Theta0>
<Sigma0>0.0</Sigma0>
</data>
</settings>
</COSUMO>

T
20.1.4 FF2NF.xml file
Below is an example <FF2NF.xml> file generated by cosumo_bmi, to be read by COSUMO.
AF Remarks:
⋄ Settings from the <COSUMOsettings.xml> file are echoed in here.
⋄ See COSUMO manual for more details.
<?xml version="1.0" encoding="utf-8"?>
<COSUMO>
<fileVersion>0.3</fileVersion>
<comm>
<Filename>COSUMO\FF2NF\FF2NF_UPKWVF_2dis_001_SubMod002_40.000.xml</Filename>
<waitForFile>COSUMO\NF2FF\NF2FF_UPKWVF_2dis_001_SubMod002_40.000.xml</waitForFile>
<FFrundir>/folder/to/workingDirectory</FFrundir>
<FFinputFile>runid.mdf</FFinputFile>
<FFuniqueID>UPKWVF</FFuniqueID>
DR
</comm>
<SubgridModel>
<SubgridModelNr>2</SubgridModelNr>
<TIME>0.40000000000000000E+02</TIME>
<constituentsNames>
Temperature
tracer
</constituentsNames>
<cormix>
<HA>0.10044436851301324E+02 0.10087161007500129E+02</HA>
<HD>0.10087687181911859E+02 0.10087687181911859E+02</HD>
<UA>0.16860016896497312E+01 0.16839284598102089E+01</UA>
<UorS>U U</UorS>
<RHOAM>1022.882 1022.891</RHOAM>
<STYPE>- -</STYPE>
<RHOAS>- -</RHOAS>
<RHOAB>- -</RHOAB>
<HINT>- -</HINT>
<DROHJ>- -</DROHJ>
<Q0>0.10000000000000000E+02 0.10000000000000000E+02</Q0>
<RHO0>0.10203153693903616E+04 0.10203153693903616E+04</RHO0>
<D0>0.25000000000000000E+01 0.25000000000000000E+01</D0>
<PHI>0.016 359.946</PHI>
<S1>-0.87687181911859632E-01 -0.87687181911859632E-01</S1>
<h_dps>0.10000000000000000E+02 0.10000000000000000E+02</h_dps>
<x_diff>0.13500000000000000E+04 0.13500000000000000E+04</x_diff>
<y_diff>0.85000000000000000E+03 0.85000000000000000E+03</y_diff>
<taua>0.35998429477578065E+03 0.54386433951378876E-01</taua>
</cormix>
<FFDiff>
<XYZ>
0.13500000000000000E+04 0.85000000000000000E+03 0.50438435909559298E+00
0.13500000000000000E+04 0.85000000000000000E+03 0.15131530772867789E+01
0.13500000000000000E+04 0.85000000000000000E+03 0.25219217954779647E+01
0.13500000000000000E+04 0.85000000000000000E+03 0.35306905136691502E+01

Deltares 290 of 562

 Coupling with Nearfield data via COSUMO

0.13500000000000000E+04 0.85000000000000000E+03 0.45394592318603362E+01

0.13500000000000000E+04 0.85000000000000000E+03 0.55482279500515217E+01
0.13500000000000000E+04 0.85000000000000000E+03 0.65569966682427072E+01
0.13500000000000000E+04 0.85000000000000000E+03 0.75657653864338927E+01
0.13500000000000000E+04 0.85000000000000000E+03 0.85745341046250783E+01
0.13500000000000000E+04 0.85000000000000000E+03 0.95833028228162647E+01
</XYZ>
<waterLevel>
-0.87687181911859632E-01
</waterLevel>
<XYvelocity>
0.18634752863723187E+01 -0.65423130314603509E-04

T
0.18440910975357934E+01 -0.75752086320958088E-04
0.18205156937121281E+01 -0.88198565822350397E-04
0.17912584190512835E+01 -0.10340229548004782E-03
0.17553731372697654E+01 -0.12157407948827463E-03
0.17113303098565760E+01 -0.14292104796713966E-03
0.16562845706940919E+01 -0.16767438429836248E-03
0.15846208832750814E+01 -0.19590817071806193E-03
AF 0.14835159394973303E+01 -0.22652941333490347E-03
0.13143232417856638E+01 -0.25073039928090045E-03
</XYvelocity>
<rho>
0.10228927346557822E+04
0.10228925528287078E+04
0.10228925573324485E+04
0.10228926721853319E+04
0.10228928369848645E+04
0.10228929327129407E+04
0.10228929247694515E+04
0.10228927989582477E+04
0.10228925577392596E+04
DR

0.10228923390834573E+04
</rho>
<constituents>
0.14992404423794710E+02 0.99999999999999956E+00
0.14993260801272069E+02 0.99999999999999956E+00
0.14993239589741927E+02 0.99999999999999967E+00
0.14992698653658509E+02 0.99999999999999956E+00
0.14991922455257015E+02 0.99999999999999933E+00
0.14991471568012786E+02 0.99999999999999911E+00
0.14991508982855612E+02 0.99999999999999933E+00
0.14992101561293641E+02 0.99999999999999911E+00
0.14993237673759108E+02 0.99999999999999900E+00
0.14994267466736535E+02 0.99999999999999900E+00
</constituents>
</FFDiff>
<FFIntake>
<XYZ>
0.13656500000000001E+04 0.34983420000000001E+03 0.50432409160155689E+00
0.13656500000000001E+04 0.34983420000000001E+03 0.15129722748046710E+01
0.13656500000000001E+04 0.34983420000000001E+03 0.25216204580077846E+01
0.13656500000000001E+04 0.34983420000000001E+03 0.35302686412108981E+01
0.13656500000000001E+04 0.34983420000000001E+03 0.45389168244140121E+01
0.13656500000000001E+04 0.34983420000000001E+03 0.55475650076171252E+01
0.13656500000000001E+04 0.34983420000000001E+03 0.65562131908202392E+01
0.13656500000000001E+04 0.34983420000000001E+03 0.75648613740233523E+01
0.13656500000000001E+04 0.34983420000000001E+03 0.85735095572264655E+01
0.13656500000000001E+04 0.34983420000000001E+03 0.95821577404295795E+01
</XYZ>
<waterLevel>
-0.86481832031138614E-01
</waterLevel>
<XYvelocity>
0.18818301897771481E+01 -0.41131954003087163E-04
0.18620821293796870E+01 -0.51252479552073700E-04

Deltares 291 of 562

 Coupling with Nearfield data via COSUMO

0.18380816955559764E+01 -0.63488977655451589E-04
0.18083027580156026E+01 -0.78497113307481159E-04
0.17717742093295803E+01 -0.96507535602107604E-04
0.17269543380078383E+01 -0.11776490852935577E-03
0.16710270758615824E+01 -0.14255875243078517E-03
0.15984082611615054E+01 -0.17106797450662620E-03
0.14962939551442496E+01 -0.20245260897418325E-03
0.13259941391355654E+01 -0.22864590576560917E-03
</XYvelocity>
<rho>
0.10228854330432104E+04
0.10228854437812954E+04

T
0.10228854562015631E+04
0.10228854708553444E+04
0.10228854878069217E+04
0.10228855070823315E+04
0.10228855286756180E+04
0.10228855525062595E+04
0.10228855781668173E+04
AF 0.10228856032910751E+04
</rho>
<constituents>
0.15026768296882313E+02 0.99999999999999978E+00
0.15026717798282352E+02 0.99999999999999978E+00
0.15026659388645221E+02 0.99999999999999967E+00
0.15026590475116326E+02 0.99999999999999989E+00
0.15026510755293693E+02 0.10000000000000000E+01
0.15026420106616042E+02 0.99999999999999978E+00
0.15026318556960202E+02 0.99999999999999956E+00
0.15026206484863748E+02 0.99999999999999978E+00
0.15026085806309688E+02 0.10000000000000000E+01
0.15025967649284215E+02 0.10000000000000000E+01
DR

</constituents>
</FFIntake>
<FFAmbient>
<XYZ>
0.16893399999999999E+04 0.83278899999999999E+03 0.50222184256506619E+00
0.16893399999999999E+04 0.83278899999999999E+03 0.15066655276951988E+01
0.16893399999999999E+04 0.83278899999999999E+03 0.25111092128253309E+01
0.16893399999999999E+04 0.83278899999999999E+03 0.35155528979554629E+01
0.16893399999999999E+04 0.83278899999999999E+03 0.45199965830855948E+01
0.16893399999999999E+04 0.83278899999999999E+03 0.55244402682157272E+01
0.16893399999999999E+04 0.83278899999999999E+03 0.65288839533458596E+01
0.16893399999999999E+04 0.83278899999999999E+03 0.75333276384759920E+01
0.16893399999999999E+04 0.83278899999999999E+03 0.85377713236061243E+01
0.16893399999999999E+04 0.83278899999999999E+03 0.95422150087362567E+01
0.13082700000000000E+04 0.71260299999999995E+03 0.50435805037500647E+00
0.13082700000000000E+04 0.71260299999999995E+03 0.15130741511250194E+01
0.13082700000000000E+04 0.71260299999999995E+03 0.25217902518750321E+01
0.13082700000000000E+04 0.71260299999999995E+03 0.35305063526250446E+01
0.13082700000000000E+04 0.71260299999999995E+03 0.45392224533750571E+01
0.13082700000000000E+04 0.71260299999999995E+03 0.55479385541250696E+01
0.13082700000000000E+04 0.71260299999999995E+03 0.65566546548750830E+01
0.13082700000000000E+04 0.71260299999999995E+03 0.75653707556250955E+01
0.13082700000000000E+04 0.71260299999999995E+03 0.85740868563751071E+01
0.13082700000000000E+04 0.71260299999999995E+03 0.95828029571251214E+01
</XYZ>
<waterLevel>
-0.44436851301324229E-01
-0.87161007500128396E-01
</waterLevel>
<XYvelocity>
0.18661537625494253E+01 -0.49366424296911108E-03
0.18471012743117909E+01 -0.49009395919670366E-03
0.18239800958890944E+01 -0.48552181171841280E-03
0.17952748109803749E+01 -0.47968468355273462E-03

Deltares 292 of 562

 Coupling with Nearfield data via COSUMO

0.17599596219659430E+01 -0.47254837584717526E-03
0.17163722300563427E+01 -0.46418653024982002E-03
0.16614795392077935E+01 -0.45474119036623513E-03
0.15893375561451455E+01 -0.44419780292137806E-03
0.14865823068086272E+01 -0.43119016983203832E-03
0.13137750651930324E+01 -0.40563453546634822E-03
0.18656908317901597E+01 0.18170783410017626E-02
0.18462618374506266E+01 0.17982146905653733E-02
0.18226279443100606E+01 0.17750156766796000E-02
0.17932667921863070E+01 0.17451632889557401E-02
0.17571938867882322E+01 0.17063017989827256E-02
0.17128557987268032E+01 0.16547532684783187E-02

T
0.16574336733219286E+01 0.15843060342165156E-02
0.15853619219655999E+01 0.14838805756680281E-02
0.14839126603310422E+01 0.13324351571148145E-02
0.13146716649400929E+01 0.10870739127617247E-02
</XYvelocity>
<rho>
0.10228822123610827E+04
AF 0.10228821429023594E+04
0.10228819887936504E+04
0.10228817850054177E+04
0.10228815897850097E+04
0.10228814566462096E+04
0.10228814297320561E+04
0.10228815246915606E+04
0.10228817189527225E+04
0.10228819512385468E+04
0.10228912677595583E+04
0.10228912655445724E+04
0.10228912692015710E+04
0.10228912765903282E+04
DR

0.10228912848435131E+04
0.10228912904465891E+04
0.10228912911869041E+04
0.10228912861229883E+04
0.10228912758342422E+04
0.10228912642271267E+04
</rho>
<constituents>
0.15041909278602565E+02 0.10000000000000007E+01
0.15042235704076928E+02 0.10000000000000007E+01
0.15042959930419553E+02 0.10000000000000009E+01
0.15043917587557827E+02 0.10000000000000009E+01
0.15044834944004041E+02 0.10000000000000007E+01
0.15045460552575548E+02 0.10000000000000002E+01
0.15045587017923388E+02 0.10000000000000000E+01
0.15045140815082185E+02 0.10000000000000000E+01
0.15044227978676414E+02 0.10000000000000002E+01
0.15043136415270279E+02 0.10000000000000007E+01
0.14999312349324843E+02 0.99999999999999933E+00
0.14999322778559403E+02 0.99999999999999978E+00
0.14999305559622911E+02 0.99999999999999944E+00
0.14999270769702697E+02 0.99999999999999911E+00
0.14999231909566548E+02 0.99999999999999889E+00
0.14999205527433457E+02 0.99999999999999889E+00
0.14999202041651518E+02 0.99999999999999900E+00
0.14999225885148908E+02 0.99999999999999911E+00
0.14999274329731929E+02 0.99999999999999900E+00
0.14999328981733916E+02 0.99999999999999889E+00
</constituents>
</FFAmbient>
</SubgridModel>
<settings>
<general>
<subgridmodel>cormix</subgridmodel>

Deltares 293 of 562

 Coupling with Nearfield data via COSUMO

<id>Diffusor_1</id>
<farfieldmodel>Delft3D</farfieldmodel>
<preprocessfcn></preprocessfcn>
<postprocessfcn>postProcessFcn_coupleAtVerticalMixingSpreadSinks</postprocessfcn>
<cmxfile>/path/to/cormix_file.cmx</cmxfile>
</general>
<comm>
<ff2nfdir>COSUMO\FF2NF\</ff2nfdir>
<ffrundir>rundir</ffrundir>
</comm>
<data>
<xydiff>550.0 350.0</xydiff>

T
<xyambient>823.0 344.8</xyambient>
<xyambient>465.8 793.2</xyambient>
<xyambient>587.4 509.2</xyambient>
<xyintake>567.0 821.3453</xyintake>
<discharge>
<m3s>10.0</m3s>
<constituentsoperator>excess</constituentsoperator>
AF <constituents>10.0 0.0 0.0</constituents>
</discharge>
<d0>2.5</d0>
<h0>3.2</h0>
<theta0>15.0</theta0>
<sigma0>0.0</sigma0>
</data>
</settings>
<settings>
<general>
<subgridmodel>cormix</subgridmodel>
<id>Diffusor_3</id>
<farfieldmodel>Delft3D</farfieldmodel>
DR

<preprocessfcn></preprocessfcn>
<postprocessfcn>postProcessFcn_coupleAtVerticalMixingSpreadSinks</postprocessfcn>
<cmxfile>/path/to/cormix_file.cmx</cmxfile>
</general>
<comm>
<ff2nfdir>COSUMO\FF2NF\</ff2nfdir>
<ffrundir>rundir</ffrundir>
</comm>
<data>
<xydiff>1350.0 850.0</xydiff>
<xyambient>1689.34 832.789</xyambient>
<xyambient>1308.27 712.603</xyambient>
<xyintake>1365.65 349.8342</xyintake>
<discharge>
<m3s>10.0</m3s>
<constituentsoperator>excess</constituentsoperator>
<constituents>10.0 0.0 0.0</constituents>
</discharge>
<d0>2.5</d0>
<h0>3.2</h0>
<theta0>15.0</theta0>
<sigma0>0.0</sigma0>
</data>
</settings>
</COSUMO>

20.1.5 NF2FF.xml file

Below is an example <NF2FF.xml> file generated by COSUMO, to be read by cosumo_bmi.

Remark:
⋄ See COSUMO manual for more details.

Deltares 294 of 562

 Coupling with Nearfield data via COSUMO

<?xml version="1.0" encoding="utf-8"?>

<NF2FF>
<fileVersion>0.3</fileVersion>
<discharge>
<M3s>10.0</M3s>
Operator: "absolute" values or "excess" (dT,dS,d..) -->
<constituentsOperator>excess</constituentsOperator>
<constituents>10.0 0.0 0.0</constituents>
</discharge>
<velocity>
COSUMO should produce a file that ONLY contains a discharge block OR a velocity block -
</velocity>

T
<NFResult>
<sinks>
550.000 350.087 9.700 1.000 0.000 0.000
552.500 350.048 9.700 1.600 0.250 0.380
555.000 350.008 9.700 1.900 0.500 0.750
557.500 350.958 9.700 2.100 0.750 1.120
AF
560.000 350.919 9.700 2.300 1.000 1.500
562.500 350.869 9.700 2.400 1.250 1.880
565.000 350.830 9.570 2.600 1.500 2.250
567.500 350.790 9.220 2.700 1.750 2.620
570.000 350.741 8.860 2.800 2.000 3.000
572.500 350.701 8.510 2.900 2.250 3.380
575.000 350.662 8.150 3.000 2.500 3.750
577.500 350.612 7.800 3.100 2.750 4.120
580.000 350.573 7.440 3.200 3.000 4.500
582.500 350.533 7.090 3.300 3.250 4.880
585.000 350.483 6.730 3.400 3.500 5.250
587.500 350.444 6.370 3.500 3.750 5.620
590.000 350.394 6.020 3.600 4.000 6.000
DR

592.500 350.355 5.660 3.600 4.250 6.380

595.000 350.315 5.310 3.700 4.500 6.750
597.500 350.266 4.950 3.800 4.750 7.130
600.000 350.226 4.600 3.900 5.000 7.500
602.500 350.187 4.240 3.900 5.250 7.880
605.000 350.137 3.890 4.000 5.500 8.250
607.500 350.097 3.530 4.100 5.750 8.620
610.000 350.058 3.180 4.100 6.000 9.000
612.500 350.008 2.820 4.200 6.250 9.380
615.000 350.969 2.470 4.300 6.500 9.750
617.500 350.919 2.120 4.300 6.750 10.120
620.000 350.880 1.760 4.400 7.000 10.500
622.500 350.840 1.410 4.400 7.250 10.880
625.000 350.791 1.050 4.500 7.500 11.250
627.500 350.751 0.950 4.600 7.500 11.620
630.000 350.711 0.840 4.600 7.500 12.000
632.500 350.662 0.740 4.700 7.500 12.380
635.000 350.622 0.630 4.700 7.500 12.750
637.500 350.583 0.530 4.800 7.500 13.130
640.000 350.533 0.420 4.800 7.500 13.500
642.500 350.494 0.320 4.900 7.500 13.880
645.000 350.444 0.210 4.900 7.500 14.250
647.500 350.405 0.110 5.000 7.500 14.630
</sinks>
<sources>
650.000 350.365 -0.000 5.000 7.500 15.000
</sources>
</NFResult>
</NF2FF>

Deltares 295 of 562

21 Calibration and data assimilation
Note: Calibration of D-Flow FM with OpenDA is a β -functionality.

21.1 Introduction
A flow model in D-Flow FM will generally benefit from parameter calibration to closer match
observation data. When the model runs in an operational system data assimilation can be
used to into the running model. For the automatic calibration and data assimilation, the open
source toolbox OpenDA is available.

T
OpenDA basically provides three types of building blocks: an optimisation algorithm that per-
forms the calibration or data assimilation, communication routines for passing information
between OpenDA and D-Flow FM, and methods for handling observation data. The commu-
nication between OpenDA and D-Flow FM is realised using a Black Box approach. A number
AF of wrapper objects (so called dataObjects) are available for reading and writing D-Flow FM
input and output files.

This chapter contains a description of how the OpenDA toolbox could be deployed to apply
calibration and data assimilation.

The OpenDA tools can run D-Flow FM models and analyze the model results. More informa-
tion on OpenDA can be found on the website http://www.openda.org.

General information on the installation of OpenDA to get started is provided in section 21.2.
section 21.4 gives an overview of the black box wrapper for D-Flow FM. section 21.4 describes
DR

the OpenDA configuration and the related D-Flow FM files. The generation of noise and how
this noise is added to forcings and boundaries is given in section 21.5. Examples for calibra-
tion and data assimilation using the ensemble Kalman filter are described in section 21.6.

21.2 Getting started with OpenDA

The required D-Flow FM wrapper is enclosed in the official OpenDA release since version
3.0.3. The following three elements are needed for a calibration or data assimilation run with
D-Flow FM:
1 The D-Flow FM Command Line Interface (CLI) installation. All OpenDA algorithms start
D-Flow FM with a shell script start_dimr.sh or a batch script start_dimr.bat.
The start_dimr scripts are positioned in the .
bin directory of the various examples (see the section 21.6 section.). They specify the
path to the run_dimr) scripts that actually perform the computation, and are part of
the Delft3D Flexible Mesh Suite installation. The name _dimr refers to the Deltares
Integrated Model Runner, the main application that starts a D-Flow FM run.
2 An OpenDA installation including the OpenDA core, the D-Flow FM specific wrapper code
and examples.
3 A Java Runtime Environment (JRE) version 8 (or higher) is needed to run OpenDA (3.0.3).
OpenDA can use one of the system installed JREs or alternatively an JRE can be installed
directly in the OpenDA directory at the same level as the <bin> directory.

For Linux it is required to run source settings_local.sh to setup OpenDA. The

OpenDA GUI can be started from the <bin> directory using oda_run_gui.bat (Win-
dows) or oda_run.sh with the -gui command line option (Linux).

Deltares 296 of 562

 Calibration and data assimilation

21.3 The OpenDA black box model wrapper for D-Flow FM

For a D-Flow FM model to function within the OpenDA toolbox we need to establish two things:
1 the control to propagate the model over time and
2 access to the model state, physical parameters, boundary conditions and external forc-
ings.

In the black box approach the standard D-Flow FM command line executable is used to prop-
agate the model over time. Access to the model state, physical parameters, boundary con-

T
ditions and external forcings is obtained by reading from and writing to the D-Flow FM input
and output files. Inside OpenDA all data is available in the form of exchange items which all
have an unique identifier.

Calibration and data assimilation typically need multiple model evaluations with altered pa-
AF rameters, forcings, boundary conditions or the initial model state. In the black box approach
this is achieved by creating multiple work directories containing altered model input files and
starting the D-Flow FM executable in each work directory. D-Flow FM model results are than
read from the work directories and compared to observation data.

For calibration this is an iterative process. Results from model evaluations 1, . . . , n are re-
quired to obtain a better estimate for parameter values, which are then evaluated in run n + 1.

In case of an ensemble Kalman filter (EnKF) run, the D-Flow FM computations (one run for
each ensemble member) is stopped each time observations are available. The input files for
each ensemble member are modified according to the ensemble Kalman filter algorithm, after
DR

which the D-Flow FM run is restarted.

Next to the D-Flow FM model configuration OpenDA has its own configuration for selecting
the algorithm, observations and interfacing with the D-Flow FM input an output files.

21.4 OpenDA configuration

21.4.1 Main configuration file and the directory structure

The OpenDA main configuration file has the .oda extension. All OpenDA configuration files
use the xml format. It is advised to use a schema aware xml editor, when making changes to
the OpenDA configuration. These editors provide direct access to the documentation that is
stored in the schema and can validate the correctness of the xml files.

All other xml config file names and directories are configurable. However, there is a commonly
used directory layout and naming convention. All the examples are configured using this
convention. For example, the directory structure for the simple_waal_kalman example is given
in Table 21.1.

All the work directories are available in the <stochModel> directory, after performing a run
with OpenDA they contain the D-Flow FM results.

It is a good practice to name the main configuration file corresponding to the algorithms exe-
cuted by OpenDA. The following files are used in the provided examples:
⋄ <Simulation.oda>: performs a regular D-Flow FM simulation run, only the executable is
started by OpenDA. This algorithm is useful to check the configuration.
⋄ <Dud.oda>: Dud (Doesn’t Use Derivative) is one of the optimisation algorithms available
for calibration purposes.

Deltares 297 of 562

 Calibration and data assimilation

<simple_waal_kalman>
<algorithm> .................. calibration method or data-assimilation algorithm
<enkfAlgorithm.xml>.....................algorithm specific configuration
...
<stochModel>............................model and its uncertainty description
<bin> ........................... .bat and .sh scripts for calling D-Flow FM
<input_dflowfm>........................D-Flow FM template configuration
...
<work0/> ............................... work directory for propagated mean
<work1/>...........................work directory for first ensemble member

T
...
<dflowfmModel.xml>........................exchange items configuration
<dflowfmStochModel.xml> ................ predictor, state and parameter
<dflowfmWrapper.xml>.............actions and data objects configuration
...
<stochObserver>...............................observations and uncertainty
AF <noosObservations.xml> .................. observations and uncertainty
<waterlevel_Obs01.noos>..........................raw observation file
...
<Enkf.oda> ............................................ main configuration file
...
Table 21.1: Directory structure of the OpenDA Ensemble Kalman filtering configuration
for the simple Waal D-Flow FM model.

⋄ <SequentialSimulation.oda>: performs a D-Flow FM simulation run through which the

DR

executable is stopped and restarted by OpenDA at the moments for which observed data
are available.
⋄ <Enkf.oda>: performs an ensemble Kalman filtering.

The main configuration for an OpenDA application has three mandatory components, which
make up an OpenDA application: stochModelFactory, stochObserver and algorithm.
Each component is configured by specifying its className attribute, workingDirectory
and configFile/configString. There are optional components to enable writing
OpenDA results, to define OpenDA restart input and output files and to enable timings. The
resultwriter is typically useful for writing stochastic properties that are only available to
OpenDA and not in D-Flow FM.

The main configuration file <Enkf.oda> for the estuary_kalman_FMSuite2019.01_bcfile

example:
<?xml version="1.0" encoding="UTF-8"?>
<openDaApplication xmlns="http://www.openda.org"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.openda.org/openDaApplication.xsd">
<stochObserver className="org.openda.observers.NoosTimeSeriesStochObserver">
<workingDirectory>./stochObserver</workingDirectory>
<configFile>noosObservations.xml</configFile>
</stochObserver>
<stochModelFactory className="org.openda.blackbox.wrapper.BBStochModelFactory">
<workingDirectory>./stochModel</workingDirectory>
<configFile>dflowfmStochModel.xml</configFile>
</stochModelFactory>
<algorithm className="org.openda.algorithms.kalmanFilter.EnKF">
<workingDirectory>./algorithm</workingDirectory>
<configString>EnkfAlgorithm.xml</configString>
</algorithm>

Deltares 298 of 562

 Calibration and data assimilation

<timingSettings doTiming="true"></timingSettings>
<resultWriter className="org.openda.resultwriters.PythonResultWriter">
<workingDirectory>.</workingDirectory>
<configFile>Enkf_results.py</configFile>
<selection>
<resultItem id="pred_f"/>
<resultItem id="pred_f_0"/>
<resultItem id="pred_f_1"/>
<resultItem id="pred_a"/>
<resultItem id="pred_a_0"/>
<resultItem id="pred_a_1"/>
<resultItem id="pred_f_std"/>

T
<resultItem id="pred_f_central"/>
<resultItem id="pred_a_central"/>
<resultItem id="pred_a_linear"/>
<resultItem id="analysis_time"/>
<resultItem id="obs"/>
</selection>
</resultWriter>
AF </openDaApplication>

Note that the directory layout in this section is created by setting the workingDirectory
elements in stochModelFactory, stochObserver and algorithm parts of the con-
figuration. Each of these components have their own configuration, which are described in
the following sections.

21.4.2 The algorithm configuration

All provided methods for calibration and data assimilation are configurable through an xml file.
DR

The convention is to include the algorithm name in the file name e.g <EnkfAlgorithm.xml>.
For data assimilation algorithms the configuration typically specifies the ensemble size and
the option to use stochastic parameters, forcing and initialisation. For calibration algorithms
the configuration typically contains definition of the cost function and tolerances and stop-
ping criteria. For a list of algorithms and their configuration options see the general OpenDA
documentation.

21.4.3 The stochObserver configuration

The access to observations is standardized in OpenDA using a stochObserver object.
The configuration and the observation data are placed in the <stochObserver> directory.
OpenDA contains a number of different stochObserver objects that can handle different
types of data files. In this manual, we discuss the NoosTimeSeriesStochObserver
and the more generic IoObjectStochObserver. For a more complete list of available
stochObservers see the OpenDA web site.

21.4.3.1 NoosTimeSeriesStochObserver
The NOOS file format is used to store time series. The format is created for use by the
members of the North West European Shelf Operational Oceanographic System http://www.
noos.cc/. An example of (a part of) a NOOS file is:
#------------------------------------------------------
#------------------------------------------------------
# Location : station01
# Position : (0.0,0.0)
# Source : twin experiment DFlowFM
# Unit : waterlevel
# Analyse time: null
# Timezone : null

Deltares 299 of 562

 Calibration and data assimilation

#------------------------------------------------------
199101010000 1.0000
199101010100 0.8944
199101010200 0.6862
199101010300 0.5956
199101010400 0.3794
199101010500 0.1372
199101010600 -0.1300
199101010700 -0.3044
199101010800 -0.3963
199101010900 -0.3739
199101011000 -0.1930

T
...

The file contains a header with meta data specifying among others the location name (Location)
and the quantity (Unit). The data is written in two columns, the first gives the time of the
observation using the ‘YYYYMMDDhhmm’ format and the second column gives the measured
AF value.

The file <noosObserver.xml> defines a number of time series, each coupled to a NOOS file
containing the measurements.
<?xml version="1.0" encoding="UTF-8"?>
<noosObserver xmlns="http://www.openda.org"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.openda.org/observation/noosObservations.xsd">
<timeSeries status="use" standardDeviation="0.005"
minDateTime="199101010000" maxDateTime="199101030000">
waterlevel_station01.noos
</timeSeries>
DR

<timeSeries status="use" standardDeviation="0.005"

minDateTime="199101010000" maxDateTime="199101030000">
waterlevel_station02.noos
</timeSeries>
<timeSeries status="use" standardDeviation="0.005"
minDateTime="199101010000" maxDateTime="199101030000">
waterlevel_station03.noos
</timeSeries>
</noosObserver>

OpenDA creates an exchange item for each observation time series. The default exchange
item id (identifier) is created using the location (Location) and the quantity (Unit). The
standard deviation (measurement error) is specified with standDeviation attribute.

21.4.3.2 IoObjectStochObserver
This observer uses a dataObject for accessing the file(s) containing the measurements. All
exchange items that are provided by a specific dataObject can be used by the observer. For
instance the NetcdfDataObject can read and write to netCDF files, and has an exchange item
for each variable in the netCDF file. The lake_kalman example uses this approach to use
the *.his file from a D-Flow FM run as synthetic observations for a ensemble Kalman filter
run. The <dflowfmStochObsConfig.xml> file reads:
<?xml version="1.0" encoding="UTF-8"?>
<ioObjectStochObserver
xmlns="http://www.openda.org"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation
="http://www.openda.org http://schemas.openda.org/openDaStochObserver.xsd">
<uncertaintyModule
workingDirectory="."

Deltares 300 of 562

 Calibration and data assimilation

className="org.openda.uncertainties.UncertaintyEngine">
<arg>stochObsUncertainties.xml</arg>
</uncertaintyModule>
<ioObject
workingDirectory="."
className="org.openda.exchange.dataobjects.NetcdfDataObject">
<fileName>lake2d_his.nc</fileName>
</ioObject>
</ioObjectStochObserver>

In the configuration of UncertaintyEngine OpenDA object, a selection of these ex-

T
change items id’s is made and a standard deviation is specified.
<?xml version="1.0" encoding="UTF-8"?>
<uncertainties
xmlns="http://www.wldelft.nl"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
AF xsi:schemaLocation
="http://www.wldelft.nl http://schemas.openda.org/uncertainties.xsd"
version="1.0">
<uncertaintyType>ProbabilityDistributionFunction</uncertaintyType>
<probabilityDistributionFunction id="S1.waterlevel" isActive="true">
<normal mean="0" stdv="0.05" stdvIsFactor="false"/>
</probabilityDistributionFunction>
<probabilityDistributionFunction id="S2.waterlevel" isActive="true">
<normal mean="0" stdv="0.05" stdvIsFactor="false"/>
</probabilityDistributionFunction>
<probabilityDistributionFunction id="S3.waterlevel" isActive="true">
<normal mean="0" stdv="0.05" stdvIsFactor="false"/>
</probabilityDistributionFunction>
DR

<probabilityDistributionFunction id="S4.waterlevel" isActive="true">

<normal mean="0" stdv="0.05" stdvIsFactor="false"/>
</probabilityDistributionFunction>
</uncertainties>

21.4.4 The stochModel configuration

The stochModel configuration usually consists of three <∗.xml> files in the <stochModel>
directory. These are called:
⋄ <dflowfmWrapper.xml>: This file specifies the actions to perform in order to run a D-
Flow FM simulation and list the D-Flow FM input and output files that can be used to let
OpenDA interact with the model. For each file the dataObject is specified which is used
for handling the specified file.
⋄ <dflowfmModel.xml>: This file contains a list of the exchange items which are provided
by the configured dataObject. The model time information is constructed by the time-
InfoExchangeItems element. It also contains a number of alias values which can be
used in three stochModel configuration files.
⋄ <dflowfmStochModel.xml>: In this file defines the predictor, the selection of observations
which are compared to the model results. For calibration this file also specifies which
parameters can be changed. For data assimilation this files contains the definition of the
model state and the noise (uncertainty) specification for the boundaries and forcings.

Deltares 301 of 562

 Calibration and data assimilation

21.4.5 D-Flow FM files and the OpenDA dataObjects configuration

The dataObjects for reading and writing provide so-called exchange items that allow OpenDA
to manipulate specific parts of the files of D-Flow FM. The D-Flow FM files that can be manip-
ulated by OpenDA and the corresponding OpenDA class names are given in Table 21.2.

Table 21.2: D-Flow FM files that can be manipulated and the corresponding OpenDA
class names to be used in the <dflowfmWrapper.xml> file.

D-Flow FM OpenDA dataObject & exchange items

T
filetype
<∗.mdu> org.openda.model_dflowfm.DFlowFMTimeInfo
IDs: start_time, end_time
<∗.amu> org.openda.model_dflowfm.DFlowFMMeteoFile
AF <∗.amv>
ID: x_wind
org.openda.model_dflowfm.DFlowFMMeteoFile
IDs: y_wind
<∗.amp> org.openda.model_dflowfm.DFlowFMMeteoFile
ID: air_pressure
<∗.tim> org.openda.model_dflowfm.DFlowFMTimeSeriesDataObject
IDs: BOUNDARY_ID.#:QUANTITY
<∗.xyz> org.openda.model_dflowfm.DFlowFMXyzFile
DR

IDs: FILENAME_#
<∗_his.nc> org.openda.exchange.dataobjects.NetcdfDataObject
IDs: STATION_ID.VARIABLE_NAME
<∗_map.nc> org.openda.model_dflowfm.DFlowFMRestartFileWrapper
IDs: VARIABLE_NAME
<∗.cld> org.openda.model_dflowfm.DFlowFMCalibrationFactorFile
IDs: CalFactor-CALIBRATION_DEFINTION_NUMBER,
CalFactor-CALIBRATION_DEFINTION_NUMBER-q{DISCHARGE},
CalFactor-CALIBRATION_DEFINTION_NUMBER-h{WATERLEVEL}
<∗.ttd> org.openda.model_dflowfm.DFlowFMTrachytopeFile
IDs: RoughNr_{ROUGHNESSNR}_FormulaNr{FORMULANR}_{FORMULAPARAMETER},

RoughNr_{ROUGHNESSNR}_DISCHARGE{DISCHARGE}_FormulaNr{FORMULANR}_{FORMULAPARAMETER},

RoughNr_{ROUGHNESSNR}_WATERLEVEL{WATERLEVEL}_FormulaNr{FORMULANR}_{FORMULAPARAMETER}

All the dataObjects and their configuration are described tn the following sections.

Deltares 302 of 562

 Calibration and data assimilation

21.4.5.1 Start and end time in the model definition file (.mdu)
The start and end time are set in <∗.mdu>-file the by OpenDA using the start_time and
end_time exchange items. These are provided by the DFlowFMTimeInfo data object.

D-Flow FM reference Exchange Item Id Remark

TStart start_time RefDate and Tunit needed for interpretation

TStop end_time RefDate and Tunit needed for interpretation

T
21.4.5.2 Spatial external forcings (.xyz)
All D-Flow FM external forcings are specified via the <∗.ext> forcings file. Here a spatial
forcing can be defined by using a .xyz-file (e.g. the bed friction coefficients). For instance
AF the file <nikuradse.xyz> contains:

x1 y1 0.9994357525438934
x2 y2 0.9994357525438934
x3 y3 2.0021214673505600
x4 y4 2.0021214673505600
x5 y5 2.0021214673505600
x6 y6 2.0021214673505600

When performing calibration of a spatial field it is often required to group points in a select
DR

number of regions. The calibration then does not change the individual values but applies
a factor to all values in the group. The best approach is to create a file with multipliers (e.g
<friction_multiplier.xyz>) which are initially all equal to one.

x1 y1 1.0
x2 y2 1.0
x3 y3 1.0
x4 y4 1.0
x5 y5 1.0
x6 y6 1.0

The multiplication (or addition) with the values in nikuradse.xyz should be configured in
the *.ext file.

Group from keywords in file

One option to construct groups is to use keywords directly in the <friction_multiplier.xyz> file:

x1 y1 1.0 #friction_3
x2 y2 1.0 #friction_3
x3 y3 1.0 #friction_1
x4 y4 1.0 #friction_1
x5 y5 1.0 #friction_4
x6 y6 1.0 #friction_4

In the OpenDA wrapper config the dataObject is than configured as:

Deltares 303 of 562

 Calibration and data assimilation

<ioObject className="org.openda.model_dflowfm.DFlowFMXyzFile">
<file>friction_multiplier.xyz</file>
<id>frictionCoefFile</id>
<arg>idsFromKeywordsInFile</arg>
</ioObject>

This will create exchange items with identifier friction_3, friction_1 and friction_4.

Group from template file

T
An other options is to use a template file (<friction_multiplier_template.xyz>) with exactly the
same (x,y) coordinates as in (<friction_multiplier.xyz>). The third column is used to define
groups by using these values as group numbers:
AF x1
x2
x3
x4
x5
y1
y2
y3
y4
y5
3.0
3.0
4.0
4.0
1.0
x6 y6 1.0

In the OpenDA wrapper config the dataObject must be configured as:

<ioObject className="org.openda.model_dflowfm.DFlowFMXyzFile">
<file>friction_multiplier.xyz</file>
<id>frictionCoefFile</id>
DR

<arg>idsFromTemplateFile=friction_multiplier_template.xyz</arg>
</ioObject>

This will create an exchange item for each group with identifier ‘FILE_BASENAME + _ + num-
ber from template file’, e.g. friction_multiplier_3, friction_multiplier_4
and friction_multiplier_1.

21.4.5.3 Boundary time series (.tim)

Boundary conditions are specified as a combination of a <∗.pli> file and one or more .tim
files. The DFlowFMTimeSeriesDataObject dataObject creates exchange items for all
boundary conditions. It starts with reading the name of the external forcing file name from
the <.mdu>-file (key ExtForceFile). The <∗.ext>-file contains formatted blocks, one
for each forcing. Forcings are defined along polylines, given in .pli-files. A <∗.pli>-file is
accompanied by a <∗.cmp>- or a (number of) <∗.tim>-file(s).

Noise can be added by means of an extra block in the .ext-file. As an example, noise is
added to a boundary with a discharge imposed as:
QUANTITY =dischargebnd
FILENAME =sw_east_dis.pli
FILETYPE =9
METHOD =3
OPERAND =O

QUANTITY =dischargebnd
FILENAME =sw_east_dis_noise.pli
FILETYPE =9
METHOD =3
OPERAND =+

Deltares 304 of 562

 Calibration and data assimilation

The discharge is set by the first block (operand=O), the information in the <∗.pli>-files is
identical and noise is added as a time series: the <_noise.pli> file is always accompanied by
a (number of) <∗.tim> file(s). The location-information on the first line of the .pli-file
combined with the quantity is used to construct the exchange item identifier: location.1.-
dischargebnd. The numbering is used to discern between multiple <∗.tim>-files possibly
linked to a single <∗.pli>-file.

21.4.5.4 Meteorological boundary conditions (<∗.amu>, <∗.amv>, <∗.amp>)

OpenDA can read and write to the D-Flow FM <∗.amu>, <∗.amv> and <∗.amp> files using

T
the org.openda.model_dflowfm.DFlowFMMeteoFile dataObject. These contain
the x- and y components of the wind and the air pressure at the free surface on an equidistant
grid. In a typical data assimilation use noise fields are added to the wind. For the this purpose
OpenDA can generate a spatial noise field on an equidistant grid (see section 21.5). D-
Flow FM can combine fields defined in files on different to single field on the computational
AF
21.4.5.5
grid.

Boundary conditions in bc format (.bc)

Boundary conditions can also be specified in a <∗.bc>-file. OpenDA can read and write to
the D-Flow FM <∗.bc> files using the
org.openda.model_dflowfm.org.openda.model_dflowfm.BcFile dataObject.
This is being done in the estuary_kalman_FMSuite2019.01_bcfile example. A
specific bc file is used for noise on the boundary and in this example waterlevel_noise.bc
looks like:
DR

[forcing]
Name = eastboundary_0001
Function = timeseries
FunctionIndex = 2
Time-interpolation = linear
Quantity = time
Unit = seconds since 1991-01-01 00:00:00
Quantity = waterlevelbnd
Unit = m
0 0
3600 0

21.4.5.6 Result time series (<∗_his.nc>)

The <∗_his.nc>-file contains time series with D-Flow FM model results for a number of sta-
tions. The generic org.openda.exchange.dataobjects.NetcdfDataObject is
used for handling this type of files. The NetcdfDataObject expects a NetCDF-file that
contains dimensions time and stations plus a variable station_id of type string and
dimension stations. For each variable in this NetCDF-file with dimensions (time,stations)
an exchange item is created, that can be referred to as station_id(i).variablename.
For instance:

dimensions:
time = UNLIMITED ; // (2882 currently)
stations = 3 ;
station_name_len = 40 ;
variables:
char station_id(stations, station_name_len) ;
(containing strings Obs1, Obs2, Obs3)
double waterlevel(time, stations) ;
(containing the computed values of the waterlevel)

Deltares 305 of 562

 Calibration and data assimilation

results in three exchange items (a 1D vector in this case) with identifiers: Obs1.waterlevel,
Obs2.waterlevel and Obs3.waterlevel.

21.4.5.7 Restart file (<∗_map.nc>)

OpenDA provides the org.openda.model_dflowfm.DFlowFMRestartFileWrapper
for reading and writing the <∗_map.nc>-file. This file contains all information needed to
restart a D-Flow FM computation. Not all variables are relevant for manipulation by OpenDA:
variable names that start with ‘time’, ‘NetLink’, ‘BndLink’, ‘FlowLink’, ‘NetElem’, ‘FlowElem’,
‘NetNode’, ‘wgs84’ and ‘projected_coordinate_system’ are ignored. Variables of other types

T
than float or double are also ignored. For all other variables an exchange item is created,
where the name of the variable in the NetCDF is used as the exchange item id.

Note: for Kalman filtering it is essential that the model starts from the <∗_map.nc> file. It is
not possible to specify an initial field by setting the initialwaterlevel or initialsalinity
AF quantities in the <∗.ext> file. If you want to set an initial field using these settings, make a
custom D-Flow FM run where TStop is equal to TStart and use the created <∗_map.nc>
file for the starting point of the Kalman filtering. Also make sure that in the mdu file in the
[output] section MapFormat = 1 so the mapfile stays in the correct format for restart.

21.4.5.8 Calibration factor definition file (<∗.cld>)

The calibraction factor definition file has the following layout. This file includes examples of
the three different types of calibration definition factors and in comments the resulting names
of the exchange items for OpenDA.
DR

# [FileInformation]
# FileType = CalibrationFactorsDefinitionFile
# FileVersion = 1.0
# [CalibrationFactors]

# Non-Q-or-h-dependent
#
# calibration-class-nr calibration-factor
#
34 0.9
#
# (will lead to exchange item CalFactor-34)

# Q-dependent calibration factors

#
# calibration-class-nr DISCHARGE "Cross-section name"
# calibration-class-nr Q1 ConstantValueAtQ1
# calibration-class-nr Q2 ConstantValueAtQ2
# calibration-class-nr Q3 ConstantValueAtQ3
# calibration-class-nr Q4 ConstantValueAtQ4
#
601 DISCHARGE "cross-section name"
601 0100 1.0
601 1000 1.0
601 5500 1.0

# (will lead to exchange items:

# CalFactor-601-q0100, CalFactor-601-q1000, CalFactor-601-q5500) etc.

# Waterlevel dependent calibration factor

# calibration-class-nr WATERLEVEL "Observation station name"
# calibration-class-nr H1 ConstantValueAtH1
# calibration-class-nr H2 ConstantValueAtH2
# calibration-class-nr H3 ConstantValueAtH3
# calibration-class-nr H4 ConstantValueAtH4
#
3 WATERLEVEL "water-level station name"
3 0.45 1.0
3 0.9 1.0

Deltares 306 of 562

 Calibration and data assimilation

# (will lead to exchange items:

# CalFactor-3-h0.45 and CalFactor-3-h0.9)

OpenDA provides the org.openda.model_dflowfm.DFlowFMCalibrationFactorFile

for reading and writing the <∗.cld>-file. In the OpenDA wrapper config <dflowfmWrapper.xml>
the dataObject can be configured as:
<ioObject className="org.openda.model_dflowfm.DFlowFMCalibrationFactorFile">
<file>FlowFM.cld</file>
<id>calibFactorFileID</id>

T
</ioObject>

In the dflowfmModel.xml a listing of the exchange items which are to be used can be
found. To select all of the available exchange items from the calibration factor definition file,
the following code can be used:
AF <exchangeItems>
<vector id="allElementsFromIoObject" ioObjectId="calibFactorFileID"/>
</exchangeItems>

To select just a few of the exchange items, these can also be selected individually:
<exchangeItems>
<vector id="CalFactor-601-q0100" ioObjectId="calibFactorFileID"
elementId="CalFactor-601-q0100"/>
<vector id="CalFactor-601-q1000" ioObjectId="calibFactorFileID"
elementId="CalFactor-601-q1000"/>
<vector id="CalFactor-601-h0.45" ioObjectId="calibFactorFileID"
DR

elementId="CalFactor-601-h0.45"/>
<vector id="CalFactor-601-q0.9" ioObjectId="calibFactorFileID"
elementId="CalFactor-601-h0.9"/>
</exchangeItems>

21.4.5.9 Trachytopes roughness definition file (<∗.ttd>)

The trachytopes definition file has the following layout. This file includes examples of the
three different types of calibration definition factors and in comments the resulting names of
the exchange items for OpenDA.

# [FileInformation]
# FileType = TrachytopesRoughnessDefinitionFile
# FileVersion = 1.0
# [RoughnessDefinitions]
#
# Constant roughness definitions
# roughness-definition-code formula-number formula-parameters
# Nikuradse 0.2
7 51 0.2
# (Leads to exchange-item RoughNr_7_FormulaNr_51_A)

# Linear trachytopes: wooden barrier

9 201 5.0 1.25
# (Leads to exchange-items RoughNr_9_FormulaNr_201_A
# and RoughNr_9_FormulaNr_201_B})

# Uniform chezy value 25

10 52 25
# (Leads to exchange-item RoughNr_10_FormulaNr_52_A)

# Discharge dependent trachytopes

# roughness-definition-code DISCHARGE cross-section-name
# roughness-definition-code Q1 formula-number formula-parametersatQ1

Deltares 307 of 562

 Calibration and data assimilation

# roughness-definition-code Q2 formula-number formula-parametersatQ2

11 DISCHARGE "m=1"
11 0.0 51 0.2
11 200.0 51 0.18
11 1000.0 51 0.1
%# (Leads to exchange-items RoughNr_11_DISCHARGE0.0_FormulaNr_51_A,
# RoughNr_11_DISCHARGE200.0_FormulaNr_51_A,
# RoughNr_11_DISCHARGE1000.0_FormulaNr_51_A)

# Water-level dependent trachytopes

# roughness-definition-code WATERLEVEL observation-station-name
# roughness-definition-code ZS1 formula-number formula-parametersatZS1
# roughness-definition-code ZS2 formula-number formula-parametersatZS2
11 WATERLEVEL "obs1"

T
16 -1.2 151 4.0 0.1
16 -1 151 4.0 0.3
16 2 151 5.0 0.1
# (Leads to exchange-items RoughNr_16_WATERLEVEL-1.2_FormulaNr_151_A,
# RoughNr_16_WATERLEVEL-1.2_FormulaNr_151_B,
# RoughNr_16_WATERLEVEL-1_FormulaNr_151_A,
# RoughNr_16_WATERLEVEL-1_FormulaNr_151_B,
AF # RoughNr_16_WATERLEVEL2_FormulaNr_151_A,
# RoughNr_16_WATERLEVEL2_FormulaNr_151_B)

OpenDA provides the org.openda.model_dflowfm.dflowfm.DFlowFMTrachytopeFile

for reading and writing the <∗.cld>-file. In the OpenDA wrapper config <dflowfmWrapper.xml>
the dataObject can be configured as:
<ioObject className="org.openda.model_dflowfm.dflowfm.DFlowFMTrachytopeFile">
<file>FlowFM.ttd</file>
<id>trachytopesFileID</id>
</ioObject>
DR

In the dflowfmModel.xml a listing of the exchange items which are to be used can be
found. To select all of the available exchange items from the calibration factor definition file,
the following code can be used:
<exchangeItems>
<vector id="allElementsFromIoObject" ioObjectId="trachytopesFileID"/>
</exchangeItems>

To select just a few of the exchange items, these can also be selected individually:
<exchangeItems>
<vector id="RoughNr_7_FormulaNr_51_A" ioObjectId="trachytopesFileID"
elementId="RoughNr_7_FormulaNr_51_A"/>
<vector id="RoughNr_11_DISCHARGE0.0_FormulaNr_51_A" ioObjectId="trachytopesFileID"
elementId="RoughNr_11_DISCHARGE0.0_FormulaNr_51_A"/>
<vector id="RoughNr_16_WATERLEVEL-1.2_FormulaNr_151_A" ioObjectId="trachytopesFileID"
elementId="RoughNr_16_WATERLEVEL-1.2_FormulaNr_151_A"/>
<vector id="RoughNr_16_WATERLEVEL-1.2_FormulaNr_151_B" ioObjectId="trachytopesFileID"
elementId="RoughNr_16_WATERLEVEL-1.2_FormulaNr_151_B"/>
</exchangeItems>

21.5 Generating noise

To add uncertainty to the external forcings and the boundary conditions, OpenDA has func-
tionality for generating noise time series and spatial fields. The noise generation can be spec-
ified within the state definition in <dflowfmStochModel.xml>. For instance in the exam-
ple estuary_kalman_FMSuite2019.01_bcfile, a noise time series is created (ID
waterlevelnoise), which is added to the inflow discharge (ID eastboundary_0001.waterlevelbnd).
<?xml version="1.0" encoding="UTF-8"?>
<blackBoxStochModel xmlns="http://www.openda.org"

Deltares 308 of 562

 Calibration and data assimilation

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.openda.org/blackBoxStochModelConfig.xsd">
<modelConfig>
<file>./dflowfmModel.xml</file>
</modelConfig>
<vectorSpecification>
<state>
<noiseModel id="boundaryNoiseModelSurge"
className="org.openda.noiseModels.TimeSeriesNoiseModelFactory"
workingDirectory=".">
<configFile>BoundaryNoiseSurge.xml</configFile>
<exchangeItems>

T
<exchangeItem id="waterlevelnoise"
operation="add"
modelExchangeItemId="eastboundary_0001.waterlevelbnd"/>
</exchangeItems>
</noiseModel>
<vector id="s1"/>
<vector id="unorm"/>
AF </state>
<predictor>
<vector id="station01.waterlevel"/>
<vector id="station02.waterlevel"/>
<vector id="station03.waterlevel"/>
</predictor>
</vectorSpecification>
</blackBoxStochModel>

The config file <BoundaryNoiseSurge.xml> contains the details of the noise:

<?xml version="1.0" encoding="UTF-8"?>
DR
<timeSeriesNoiseModelConfig xmlns="http://www.openda.org"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.openda.org/noiseModels/timeSeriesNoiseModel.xsd">
<simulationTimespan timeFormat="dateTimeString">
199101010000,199101010100,...,199101050000</simulationTimespan>
<timeSeries id="waterlevelnoise" location="westboundary" quantity="waterlevel"
standardDeviation="0.05" timeCorrelationScale="1.0"
timeCorrelationScaleUnit="hours" initialValue="0.0"/>
</timeSeriesNoiseModelConfig>

A noise time series is created (ID waterlevelnoise) with a correlation time of 1 hour
and a standard deviation of 0.05. Note: currently OpenDA does not support the creation of
D-Flow FM files, all files should exist in the <input_dflowfm>. In this case the boundary is
defined in <waterlevel_surge.bc>, but the noise is in a separate file <waterlevel_noise.bc>.
Initially it contains zeros, but is filled with the noise values at run time. The time points in the
file need to match the simulationTimespan in the OpenDA config. The waterlevel at the
boundary is constructed by D-Flow FM where the noise is added to original boundary values
(see <FlowFM_bnd.ext>).

To generate a spatial correlation field the same approach can be used. In the lake_kalman
example a noise field is added the wind. Instead of timeSeries a noiseItem is specified
which contains the grid definition.
<?xml version="1.0" encoding="UTF-8"?>
<mapsNoiseModelConfig>
<simulationTimespan timeFormat="dateTimeString">
200106240000,200106240100,...,200106270000
</simulationTimespan>
<noiseItem id="2DNoise" quantity="wind-x" unit="m/s" height="10.0"
standardDeviation="20.0"
timeCorrelationScale="12.0" timeCorrelationScaleUnit="hours"
initialValue="0.0"

Deltares 309 of 562

 Calibration and data assimilation

horizontalCorrelationScale="10" horizontalCorrelationScaleUnit="km">
<grid type="cartesian" coordinates="XY">
<x>0,3000,...,63000</x>
<y>0,3000,...,63000</y>
</grid>
</noiseItem>
</mapsNoiseModelConfig>

The calculation of spatially correlated noise on a cartesian grid is quite fast as the x and
y -direction are independent. The interpolation from an equidistant grid to the computa-
tional grid is performed within D-Flow FM. Again, note that an zero valued wind files should

T
be present <input_dflowfm> folder, where the time stamps match with the ones given in
simulationTimespan in the OpenDA configuration.

21.6 Examples of the application of OpenDA for D-Flow FM

AF In this section, some examples are elaborated for both the calibration of a model and the
ensemble Kalman filtering (abbreviated as ‘EnKF’) of a model. All the examples can be found
in the directory <examples/model_dflowfm_blackbox>.

21.6.1 Example 1: Calibration of the roughness parameter

The automatic calibration of a model needs two main choices from the user:
1 Which model parameters may be modified during the calibration process?
2 Which model results need to be compared to observations, to judge the model quality?
DR

The remainder of this section will be in the form of a tutorial, to directly illustrate all steps in
an example model. In this example you will use a small river model ‘simple_waal’ and use the
bed roughness to calibrate this model for its three water level observation stations.

Step 1: Inspect the model

All the required model files can be found in the directory <simple_waal_calibration_roughness>.
Consider the following steps:
1 Start D-Flow FM (standalone) in directory <input_dflowfm/>.
2 Select Files → Load MDU-file.
3 Load the model: select <simple_waal.mdu>.
4 You can run the model if you like (right mouse button).

The basic model is built to simulate a simple two-dimensional river with a spatially varying
bed friction coefficient. It is driven by two boundary conditions: an upstream discharge inflow
at the eastern boundary and a downstream water level at the western boundary. Inspect the
model forcing in the following way:
1 Open the external forcings file <simple_waal.ext> in a text editor.
2 Notice how, in addition to the two boundaries, there are two blocks for the friction coeffi-
cient. The first one is a spatially varying roughness field in the <sw_nikuradse.xyz> file.
The second refers to the <sw_frcfact_all.xyz> file that contains multipliers for the original
friction coefficients. A third file <sw_frcfact_template.xyz> is present, which is used to
define a number of subdomains.
3 In D-Flow FM, select Files → Load sample file and select <sw_frcfact_template.xyz>.
4 Notice how the loaded samples have three distinct values 1, 2 and 3, which act as iden-
tifiers: they approximately define the corner points of three subdomains of the entire river

Deltares 310 of 562

 Calibration and data assimilation

stretch. For each subdomain, a different roughness can be calibrated.

Step 2: Select the model parameters

Currently, the only calibratable parameters are the time-independent parameters in the exter-
nal forcings file that use the .xyz sample file format. The most obvious parameter is the bed
friction coefficient.

Step 3: Select the model results

T
The example directory <simple_waal_calibration_roughness> contains all the necessary
configuration files for the so-called Black Box model wrapper for D-Flow FM to run a ‘twin ex-
periment’. In a twin experiment a model setup with given solution (the synthetic observations)
is perturbed after which OpenDA is applied to re-estimate the original settings. The effects of
the parameter variations may be judged by comparing time series output in the <∗_his.nc>
AF
history file to observed data in NOOS time series format. The model output and observation
data are compared by calculating a cost function. Which cost function is used is configured in
the <dudAlgorithm.xml> in the <algorithm> directory. See the OpenDA documentation for
the available options for the cost function.

Let’s assume that a D-Flow FM model simulates river flow and that the input files for D-
Flow FM are located in the directory <simple_waal_calibration_roughness/stochModel/input>.
D-Flow FM allows the user to specify regions with a different bed friction coefficient (constant
for each region) and is able to handle the interpolation of the coefficients between these re-
gions. In the experiment we try to re-estimate the values of the bed friction coefficients of
an earlier run. As observations, the waterlevel at three locations (stations) along the river is
DR

used. These results are written to the main output file (<∗_his.nc>) as time series.

In the directory <simple_waal_calibration_roughness>, there are two main configuration files

of OpenDA present:
⋄ Simulation.oda: runs a single run of the model, this configuration is mainly used to
test the black box configuration files.
⋄ Dud.oda runs a calibration experiment with algorithm DUD (Doesn’t Use Derivative).

These files configure the main ingredients of an OpenDA run:

1 the stochObserver (org.openda.observers.NoosTimeSeriesStochObserver).
Observations for this experiment were created by extracting the timeseries for all stations
from the netcdf-file and convert them to NOOS format (script nchis2noos.sh) het script
schrijft nog tijd sinds begin situatie.
2 the stochObserver (org.openda.observers.NoosTimeSeriesStochObserver).
Observations for this experiment were created by extracting the time series for all stations
from the netcdf-file and convert them to NOOS format (script nchis2noos.sh)
3 the stochModelFactory (org.openda.blackbox.wrapper.BBStochModelFactory). A black
box model configuration consist of three configuration files that are described in more
detail below.
4 the algorithm (org.openda.algorithms.Dud). Dud is a well known algorithm in calibration
experiments, more information about it can be found on the OpenDA website or in the
literature.

The configuration files for these 3 components are located in different sub directories to reflect
the Object Oriented architecture of OpenDA. The fourth block in the configuration file specifies
the result writer (org.openda.resultwriters.MatlabResultWriter). The resulting m-file may be

Deltares 311 of 562

 Calibration and data assimilation

loaded in Matlab to visualize results of the OpenDA run.

In this example, the data exchange between OpenDA and D-Flow FM is limited to the bed
friction coefficients and the computed waterlevel at observation locations. The waterlevel at a
observation location is expected to be written to NetCDF-file with the following features
1 dimension ‘time’ and ‘stations’ are defined
2 there exists a variable ‘station_id(stations)’ defined that contains strings with the station_id

For NetCDF-files that satisfy these two conditions OpenDA creates an ‘exchange item’ for

T
each variable that has the dimensions (time, stations). The exchange item is referred to as
‘station id(nr)’.’name of variable’.

21.6.2 Example 2: EnKF with uncertainty in the tidal components

AF The geometry for this test case is the same as used in the Delft3D-FLOW model example for
calibration that was presented in a Deltares webinar (recording, slides and all configuration
files for this example are available at the OpenDA website).

Regularly, D-Flow FM uses 1 component file to specify all tidal component (one component
at a line). In order to add different noise models to different components, you must split the
component file and add one <∗.tim>-files for noise for each component.

Again, all configuration files are available, but not much effort has been put into the exact
configuration of the EnKF algorithm or the noise model specifications. The results of the
SequentialSimulation show that this test case suffers much less from the inexact restart. The
DR

whole workflow is highlighted in more detail below.

A few remarks are made:

⋄ the directories <bin> and <jre> should be on the same level,
⋄ the computation is started through running the file oda_run_gui.bat,
⋄ the bare D-Flow FM model is located in the directory <input_dflowfm>,
⋄ the observations are in .noos-format, and are located in the directory <stochObserver>.

Step 2: Start the EnKF computation

The OpenDA run is launched through the core oda_run_gui.bat file. Once having
opened this file, a user interface appears. Within the user interface, an <∗.oda>-file can be
opened from a certain case directory (in this case, we have <estuary_kalman_FMSuite2019.01_bcfile>).
One can choose Enkf.oda, SequentialSimulation.oda or Simulation.oda. In
this case, we choose for Enkf.oda.

Step 3: Examine the applied noise

The basic necessary component of an EnKF computation comprises the noise applied to
some variable. In this case, the noise is applied to the waterlevel boundary representing the
tidal motion. Within the directory <input_dflowfm>, this noise is explicitly declared through a
separate polyline and a separate data file for the boundary. The configuration of the noise is
accomplished through two <∗.xml>-files in the directory <stoch_model>.

Deltares 312 of 562

 Calibration and data assimilation

Step 4: Run the EnKF computation

By means of the user interface, the EnKF computation can be launched. After having opened
the file <EnKF.oda>, the Run-button can be pressed. The computation is being performed.
Along the computation’s duration, multiple <work> directories are generated in the directory
<stochModel>, i.e. <work0>, <work1>, <work2>, etc.

Step 5: Evaluate the outcomes

After having run the computation, output files have been generated in Matlab-format. The
relevant files are placed in the directory <estuary_kalman>. The data are stored in the

T
Matlab file <Enkf_results.m>. Visualisation could be accomplished like shown in Figure 21.1.

AF
DR

Figure 21.1: Visualisation of the EnKF computation results from OpenDA for a certain
observation point. The dots represent the observed data, the black line rep-
resents the original computation with D-Flow FM (without Kalman filtering)
and the red line represents the D-Flow FM computation with Kalman filtering.

21.6.3 Example 3: EnKF with uncertainty in the inflow velocity

The geometry in this example is the same as for the calibration example: a two-dimensional
river model, the initial waterlevel is zero, the river bed is filled gradually due to the bound-
ary conditions. At the inflow boundary, a constant discharge is prescribed (along the line
<sw_east_dis_0001.pli>), whereas at the outflow boundary, a constant water level is pre-
scribed (along the line <sw_west_wlev_0001.cmp>).

There are 3 observation locations along the river (Obs01, Obs02 and Obs03). The mat-
lab script <plot_results_hisfile.m> is available to plot the water level as a function of time for
these 3 stations. Simulation time span is 100 days (Start: 199208310000, End: 199212090000).
The noise contribution is found in file <sw_east_dis_noise.pli>. Initially, no noise is present,
so the file contains zeroes in directory <input_dflowfm>.

Deltares 313 of 562

 Calibration and data assimilation

21.6.4 Example 4: EnKF with uncertainty in the inflow condition for salt
The geometry in this example and the boundary conditions for waterlevel and velocity are
exactly the same as in simple_waal_kalman. The transport of salt is added to the com-
putation by a discharge boundary condition sw_east_dis_sal_001.pli and a noise
component added to this boundary.

21.6.5 Example 5: EnKF with uncertainty on the wind direction

This example is also converted from a Delft3D-FLOW test case (d3d_lake_2d): a lake

T
forced by an uniform wind field. This example is a twin experiment with spatially correlated 2D-
noise added to the wind field. The noise is created on cartesian (equidistant grid), the noise
realisations are written by OpenDA to the <lake2d_windx_noise.amu>. The 2D noise field
is interpolated at computational grid by D-Flow FM and added to the uniform wind field. The
<SequentialSimulationNoise.oda> can be used to perform a single D-Flow FM run where
wind with noise is used as forcing. The resulting <lake2d_his.nc> file can be is used as
AF syntethic observations by the <stochObserver>.

21.6.6 Example 6: EnKF with the DCSM v5 model and uncertainty on the wind direction
This example is converted from the SIMONA DCSM v5 model with spatially correlated 2D-
noise added to the wind field.
DR

Deltares 314 of 562

22 Numerical aspects of D-Flow Flexible Mesh
This section contains numerical aspects of D-Flow FM.

22.1 Topological conventions for (2D) horizontal grids

In the horizontal a computational cell in a D-Flow FM grid (sometimes referred to as a ’net-
work’) consists of corner nodes and edges connecting the corner nodes. Such a grid cell
should contain at least three and at most six corner nodes, representing triangles, quadran-
gles, pentagons and hexagons, respectively. The following topological conventions are used:

T
⋄ net nodes: corners of a cell (triangles, quadrangles, ...),
⋄ net links: edges of a cell, connecting netnodes,
⋄ flow nodes: the cell circumcentre, in case of triangles the exact intersection of the three
perpendicular bisectors and hence also the centre of the circumscribing circle,
⋄ flow links: a line segment connecting two flownodes.
AF 1. Net (domain discretization)

net node (1..NUMK)

net link (1D) (1..NUML1D)
net link (2D) (NUML1D+1..NUML)
DR

2. Flow data (1D+2D)

netcell/flow node (2D) (1..NDX2D=NUMP)
netcell/flow node (1D) (NDX2D+1..NDXI)
boundary flow node (NDXI+1..NDX)

pressure points: 2D flow node circumcenter/1D flow node

flow link 1D internal (1..LNX1D)
2D internal (LNX1D..LNXI)
1D open bnd (LNXI+1..LNX1DBND)
2D open bnd (LNX1DBND+1..LNX)

Figure 22.1: Flexible mesh topology

This mesh topology is illustrated in Figure 22.1. The ’center’ of a cell can be defined in multiple
ways. To illustrate this, two conventional cell center definitions for a triangle are highlighted in
Figure 22.2. The two displayed cell centers have different properties:
1 the circumcenter is the location within the triangle which is the center point of a circle
that intersects the triangle at each corner node of the triangle; as a consequence, the
orthogonal projection of the center point to each face of the triangle divides each face into
two exactly equidistant pieces,
2 the mass center (or centroid) is the center of gravity; as a consequence, a line through a
corner node and the mass center divides a face into two exactly equidistant pieces under
an angle not necessarily equal to 90◦ .

Deltares 315 of 562

 Numerical aspects of D-Flow Flexible Mesh

T
Figure 22.2: Two conventional definitions of the cell center of a triangle: the circumcenter
AF and the mass center.

D-Flow FM utilizes the circumcenter as the basis of the definition of the elementary flow vari-
ables ’water level’ and ’flow velocity’. The water level is defined at the circumcenter, whereas
the face normal flow velocity is defined at the orthogonal projection of the circumcenter onto
the cell face, i.e., the midpoint of the cell face.

Important properties of the mesh are the orthogonality and smoothness. The orthogonality
is defined as the cosine of the angle φ between a flowlink and a netlink. Ideally 0, angle
DR

φ = 90◦ . The smoothness of a mesh is defined as the ratio of the areas of two adjacent
cells. Ideally 1, the areas of the cells are equal to each other. A nearly ideal setup is shown
in Figure 22.3.

Figure 22.3: Perfect orthogonality and nearly perfect smoothness along the edge con-
necting two triangles. Black lines/dots are network links/nodes, blue lines/-
dots are flow links/nodes.

It is quite easy (and therefore dangerous) to generate meshes that violate the orthogonality
and smoothness requirements. In Figure 22.4, two different setups of two gridcells are shown
with different mesh properties.

The left picture of Figure 22.4 shows how orthogonality can be detoriated by skewing the right
triangle with respect to the left triangle. While having the same area (perfect smoothness),
the mutually oblique orientation results in poor orthogonality. In this particular case, the centre

Deltares 316 of 562

 Numerical aspects of D-Flow Flexible Mesh

of the circumscribing circle is in principle located outside the right triangle. Such a triangle is
denoted as an ’open’ triangle, which is bad for computations.

The opposite is shown in the right picture of Figure 22.4 in which the right triangle has strongly
been elongated, disturbing the smoothness property. However, the orthogonality is nearly
perfect. Nonetheless, both meshes need to be improved to assure accurate model results.

T
AF
(a) Perfect smoothness, but poor orthogonality. (b) Perfect orthogonality, but poor smoothness

Figure 22.4: Poor mesh properties due to violating either the smoothness or the orthog-
onality at the edge connecting two triangles. Black lines/dots are network
links/nodes, blue lines/dots are flow links/nodes.

22.2 Notation
DR

The used symbols in this chapter are described in this section.

Time variables:
n Time index of the current time step.
∆tn The computational time step size of time step n.

Computational grid and primary shallow water variables:

k Computational grid index for a pressure point ("flow node"),
j Computational grid index for a velocity point ("flow link"),
Vk Volume of water in grid cell k ,
Ak Wet area of the horizontal water surface in grid cell k .
Auj Wet cross-sectional area ("flow area") of flow link j .
A1j /A2j Face-based cross-sectional area flow link j based on left or right side, respec-
tively.

When a grid cell k is mentioned, this is essentially the same as a grid point (or calculation
point) k . The term ’grid cell’ better captures the concept of a cell-integrated value (such as
volume), compared to a cell-averaged point value (such as water level).

Lateral discharges:
ℓ Index of a lateral discharge,
Llat,ℓ The set of grid cells selected for lateral discharge ℓ.
Qlat,ℓ,k The discharge of lateral ℓ for grid cell k ,
Qlat,k Total of all lateral discharges for grid cell k ,
Qin,k Total of all source terms for grid cell k ,

Deltares 317 of 562

 Numerical aspects of D-Flow Flexible Mesh

22.3 Definition of bed level options

In section 22.1, the locations of the primary flow variables (water level and flow velocity) have
been described. Through Figure 22.2 it has been clarified that the water level is computed
at the location of the circumcenter (cell center), whereas the face normal flow velocity is
computed at the midpoint of each cell face (face center).

For the computation of these two primary variables, the level of the bed must be known both
at the cell center and at the face center. The user can specify the way these values are
interpreted from the available bathymetry by means of the MDU-file keywords BedlevType,

T
DpuOpt and conveyance2D. For a proper understanding of the possibilities of D-Flow FM,
Figure 22.5 is provided with a three-dimensional representation of two adjacent triangular
cells.
AF
DR

Figure 22.5: Definition of the water levels, the bed levels and the velocities in case of two
adjacent triangular cells.

To the keyword BedlevType, the values 1, 2, 3, 4, 5 and 6 can be assigned. For the key-
word conveyance2D, the values -1, 0, 1, 2 and 3 are available. The keyword DpuOpt can
be either 1 or 2; the latter option is currently only available in combination with D-Morphology.

The most common case is the definition of the bed levels at the corner nodes of the cell and a
choice for the keyword BedlevType = 3. Depending on the choice for conveyance2D,
the face center bed levels and cell center bed levels are computed.

22.3.1 Piecewise constant approach for the bed level

In principle, the bed levels are considered as piecewise constant in space. This approach is
followed if conveyance2D < 1. The keyword BedlevType can be used in combination
with the piecewise constant approach as highlighted in the table below. Note that the bed level
is defined with respect to the reference level (not to be confused with a water depth given as
a positive value downwards). With conveyance2D < 1, we have:

Deltares 318 of 562

 Numerical aspects of D-Flow Flexible Mesh

Keyword Value Cell center bed level Face center bed level

BedlevType 1 user specified the highest1 cell center bed

level considering the two
cells next to the face

BedlevType 2 the lowest face center bed user specified

level considering all the
faces of the cell

T
BedlevType 3 the lowest face center bed the mean corner bed level
level considering all the considering the two corner
faces of the cell nodes the face is connecting

BedlevType 4 the lowest face center bed the lowest corner bed level
AF BedlevType 5
level considering all the
faces of the cell

the lowest face center bed

considering the two corner
nodes the face is connecting

the highest corner bed level

level considering all the considering the two corner
faces of the cell nodes the face is connecting

BedlevType 6 the mean corner bed level the highest1 cell center bed
considering all the corners of level considering the two
the cell cells next to the face
DR

The former Delft3D-FLOW version, running on curvilinear meshes, has utilized the piecewise
constant approach for bed levels as well. The treatment of the bed level itself is, however,
different from D-Flow FM. In Delft3D-FLOW, the user can distinctly specify the treatment type
for the cell center bed level and the face center bed level. In D-Flow FM, the choice for the
one implies the choice for the other. A strict, exact match of settings for which Delft3D-FLOW
and D-Flow FM treat the bed similarly, is not facilitated. Hence, the user himself should take
care in comparing the Delft3D-FLOW results and D-Flow FM results when it comes to the bed
level treatment settings.

22.3.2 Piecewise linear approach for the bed levels

A piecewise linear bed level approach can be chosen for through setting conveyance2D
≥ 1. In this case, only the approach for BedlevType equal to 3, 4 and 5 is affected. With
conveyance2D ≥ 1, we have:

Keyword Value Cell center bed level Face center bed level

BedlevType 3, 4, 5 the lowest corner node bed linearly varying from the bed
level considering all the level at the one corner node
nodes of the cell to the bed level at the other
corner node

Notice that the choice for either BedlevType equal to 3, 4 or 5 does not imply different
bed level treatment approaches. For the case conveyance2D ≥ 1, the bed is assumed
linearly varying within a face only to compute the wet cross-sectional area of the vertical face;
1
This is the default behaviour in case DpuOpt=1. When DpuOpt=2, the mean value of the two cells next to
the face is used. This option is only available in combination with D-Morphology.

Deltares 319 of 562

 Numerical aspects of D-Flow Flexible Mesh

it should, however, be remarked that for the computation of the water column volume in a cell,
this linear variation of the bed is not taken into account.

22.3.3 Hybrid bed level approach

In addition to the previously described bed level treatment approaches, D-Flow FM facilitates
a hybrid approach for the computation of the cell center bed level by means of the keywords
blminabove and blmeanbelow. In this approach, the cell center bed level is computed
as the mean of the associated face center bed levels, be it only below the user specified level
blmeanbelow. For levels above the user specified level blminabove, the minimum value

T
of the associated face center bed levels is used. In between these two user specified levels,
the bed levels are constructed by means of a linear interpolation between the two approaches’
results.
AF
22.3.4 Specification in the User Interface
The specification of the treatment of the bed level locations can be achieved through the tab
fields ‘Numerical Parameters’ and ‘Physical Parameters’.
DR

Figure 22.6: Specification of the conveyance option in the User Interface.

The tab field ‘Numerical Parameters’ contains the choice for the conveyance options: see
Figure 22.6).

Figure 22.7: Specification of the bed level treatment type in the User Interface.

The tab field ‘Physical Parameters’ contains the choice for the Bed level locations. Five options
are facilitated: BedlevType numbers 1 up to 5; the option 6 is not facilitated in the user
interface.

Deltares 320 of 562

 Numerical aspects of D-Flow Flexible Mesh

T
Figure 22.8: Specification of the hybrid bed options (with keywords blminabove and
blmeanbelow).

By means of the tab field ‘Miscellaneous’, the hybrid options with the keywords blminabove
AF and blmeanbelow can be enabled.

22.4 The location of open boundaries

The boundaries of a river, an estuary or a coastal sea are in general curved and are less
smoothly represented on a structured grid. The boundary becomes irregular and may intro-
duce significant discretization errors. To reduce these errors unstructured grids are used. The
unstructured grids also allow local grid refinement in areas with large horizontal gradients.

The flow engine needs the location for the boundary conditions. In 2D models, this is done by
DR

providing a polyline with support points (also see section 7.4.8.1). By default, these support
points are a means to construct a series of virtual cell centers along the boundary rim of the
grid. Figure 22.9 provides an image of the concept of virtual boundary cells in 2D.

xL(j) dj

dj xb(j)

xR(j)

Figure 22.9: Virtual boundary ’cells’ near the shaded boundary; xLj is the virtual ’cell’
pressure point near boundary edge j ; xR(j) is the inner cell’s circumcenter;
xb (j) is the point on edge j that is nearest to the inner cell’s circumcenter

Deltares 321 of 562

 Numerical aspects of D-Flow Flexible Mesh

The support points are stored as one single polyline file per boundary condition, marking the
rim along which the boundary conditions should hold. The polyline should be drawn in the
vicinity of the rim. The user can specify the size of this ‘vicinity’ by means of the MDU-file
keyword OpenBoundaryTolerance. The keyword specifies the search tolerance factor
between the boundary polyline and the grid cells. The unit of this keyword is the cell size unit
(i.e., not metres). By default, this value is 3, which loosely means that in the vicinity of 3∆x
of the grid rim is searched of a boundary condition polyline.

The actual location of a specific boundary location point can be computed in two different
ways, dependent on the user’s choice for the keyword izbndpos in the mdu-file:

T
1 izbndpos = 0: construction of the boundary condition point by means of orthogonal
mirroring of the closest cell center (default),
2 izbndpos = 1: construction of the boundary condition point as the orthogonal projec-
tion of the closest cell center onto the grid rim.
AF
The following explanation uses both the mass center and the circumcenter, which are often
different in 2D grid cells. For 1D gids, these two are identical.

Option izbndpos = 0 ’mirrors’ the internal cell closest to the boundary outward, to produce
the virtual boundary point. The mirroring of the closest cell center is conducted as follows.
First, the orthogonal distance from the cell’s mass center to the actual rim of the grid is com-
puted: dj in Figure 22.9. Second, the cell circumcenter (pressure point) xL(j) is projected
orthogonally onto the grid cell outer edge. The virtual boundary cell’s pressure point (xR(j) )
is defined at a distance 12 dj starting at that projected point xb(j) . Sometimes the flat area of
√
DR

1
the cell, say A , at the rim can give rise to an adaptation of this distance. If A > dj , then
1
√ 2
the center of the virtual cell is located at the a distance 2
A away from the grid.

The first part in Figure 22.10 shows how in a regular grid the mass center and circumcenter
coincide, with an exactly mirrored virtual boundary point. Also, the resulting placement of the
pressure points in the 2D and 1D example grid is identical.

izbndpos = 0
2D
xL(j) xR(j)
1D

izbndpos = 1
2D
xL(j) xR(j)
1D

Legend:
2D grid cell/control volume center of mass
1D grid cell/control volume pressure point
flow link (internal) boundary pressure point
flow link (boundary)

Figure 22.10: Position of virtual boundary point, depending on izbndpos setting.

Deltares 322 of 562

 Numerical aspects of D-Flow Flexible Mesh

Option izbndpos = 1 is mainly intended to force a water level boundary exactly on the
outer edge of a 2D grid cell. The second part in Figure 22.10 shows how the pressure point
now lies on that 2D edge. In 1D networks, the virtual pressure point is placed half an edge
length outward (instead of a full edge length for izbndpos = 0). This ensures that it is
possible to create a 2D gridded channel and an exactly equivalent 1D channel branch, with
the same pressure point locations.

22.4.1 Geometry of open boundaries

The virtual boundary points as introduced above inherit some additional geometric parameters

T
from their neighbouring internal grid point:
⋄ the bed level of the boundary point is set equal to the bed level of the internal pressure
point: blL(j) = blR(j) ;
⋄ the boundary flow link width is different for 1D and 2D boundaries:
AF 2D: The boundary flow link width is equal to the 2D edge width: wuj = wu′ j
⋄ ⋄

1D: The boundary flow link j inherits the entire cross section geometry of the first
neighbouring internal flow link j ′ (that is: width, area, perimeter). If no such cross
section is available on link j ′ , then the default uniform width UniformWidth1D is
used.

22.4.1.1 Conveyance in 2D
Bed friction often plays a major role in the discharge capacity and expected maximum water
levels of channels and gullies. If we model a trapezoidal channel with sloping sidewalls on a
DR

grid with 6 grid cells across the width of the channel, a typical cross section using the standard
bed representation with uniform depth appears per cell (Figure 22.11a). In D-Flow FM, we
allow for representation of a locally sloping bed as shown in Figure 22.11b.

Figure 22.11: Bed representation with uniform depth levels (a), and locally sloping bed
(b).

The most left and the most right cell are not yet wet in the uniform bed representation. In
the sloping bed representation, these outer cells are partly wet, yielding a more accurate
description of the total wet cross sectional area. The user can select whether to apply this
more accurate description or not. This can only be done only in combination with a net-node
based bathymetry description, i.e. using the keyword BedlevType = 3 in the .mdu file.

For the bed friction in 2D models, one implicitly assumes a fully developed vertical velocity
profile, using a logarithmic function of the water depth for the White-Colebrook bed friction
formulation, or a one-sixth power function of the water depth for the Manning formulation. In a
sloping cell, the local water depth is varying over the width of the cell. In the deeper part flow
velocities will be higher than in the shallower part. Bed stresses will vary over the width of a
cell with water depth and with the velocity. Integrating the stresses over the width of a cell one
can derive the resulting total stress.

The bed friction term is not only a function of the normal velocity component in the direction

Deltares 323 of 562

 Numerical aspects of D-Flow Flexible Mesh

T
AF Figure 22.12: A shematic view of the linear variation over the width for calculating the flow
parameters.

of the flow link itself, but also depends on the tangential velocity component and with that on
the total velocity. For each of the four components water depth, normal velocity, total velocity
and Chézy parameter, we assume a linear variation over the width (Figure 22.12).

If we have in the .mdu file Conveyance2D = 3, the 2D analytic conveyance description

using these four linearly varying components is applied. This option shows best grid conver-
gence behaviour. Good grid convergence implies that the converged answer can be achieved
DR

on a coarser grid, thus saving computational costs.

If one sets Conveyance2D = 2, the tangential velocity component is assumed zero. This
method is only applicable on curvilinear grids that are aligned with the flow direction.

If one sets Conveyance2D = 1, both the normal and tangential velocity component are
assumed constant over the width. Effectively one obtains the so called ’lumped’ bed friction
approach, with hydraulic radius R = A/P , A being the wet cross sectional area and P the
wet perimeter. This method works equally well as methods 2 and 1, provided that there is
sufficient resolution of a gully in the grid. It is found that when a gully is resolved by more than
about 10 or 12 cells, it provides almost identical answers as method 2, while saving some
10 % computational overhead compared to method 2.

Setting Conveyance2D = -1, the hydraulic radius is based on a uniform bed level at the
velocity point taken as the average bed level of the two surrounding net nodes.

Setting Conveyance2D = 0, the hydraulic radius is based on a uniform bed level at the
velocity point taken as the average bed level of the two surrounding water level points. This
option is not advisable because cell bed levels are taken as the minimum value of the bed
levels of attached link. So a min-max operator is invoked, which is not suitable for accuracy.

Keyword Conveyance2D deals with the bed level at the velocity points (i.e., at flow links
or cell edges) in the case of a net-node based bathymetry description (i.e. BedlevType
= 3). When using a cell-centre based bathymetry description (i.e. BedlevType = 1)
[geometry] keyword Dpuopt can be used to this end. Using the default value Dpuopt
= 1, the bed level at links is the maximum of the adjacent cell-centre bed levels (i.e. of the
bed levels connected by a link). Setting Dpuopt = 2 computes the bed level at links as the
mean value between the adjacent cell-centre bed levels.

Deltares 324 of 562

 Numerical aspects of D-Flow Flexible Mesh

Please note that setting Dpuopt = 2 should not be confused with a piece-wise linear in-
terpretation of the bed level. The bed level for BedlevType = 1 is considered piece-wise
constant and that is still the way in which the volumes are computed. The keyword Dpuopt
only changes the way in which the bed level at the interface between two tiles is computed.

The default maximum bed level at links causes the flow depth at links to be minimum, which
guarantees that there is no flooding of a dry cell of which the bed level is higher than the water
lower of the wet cell. On the contrary, using the mean bed level at links may cause a positive
flow depth at the link while the bed level of the dry cell is higher than the water level of the wet
cell.

T
Computing the bed level at links as the mean value of the adjacent cell-centres (i.e. Dpuopt
= 2) is particularly relevant for morphodynamic simulations. This increases the accuracy of
the results, as the default maximum option causes a first-order upwind/downwind reconstruc-
tion while the mean ensures a second-order central reconstruction.
AF
22.5 Drying and flooding
Estuaries and coastal embayments contain large, shallow, and relatively flat areas separated
and interleaved by deeper channels and creeks. When water levels are high, the entire area
is covered by water. But as tide falls, the shallow areas are exposed, and ultimately the flow
is confined only to the deeper channels. The dry tidal flats may occupy a substantial fraction
of the total surface area. The accurate reproduction of covering or uncovering of the tidal flats
is an important feature of numerical flow models based on the shallow water equations.

Many rivers have compound channels, consisting of a main channel that always carries flow
DR

(the summer bed) and one or two flood plains which only convey flow during extreme river
discharges (the winter bed). The summer bed is surrounded by low dykes, which could be
overtopped if the river discharge increases. The winter-bed is surrounded by much higher
dykes, which are designed to protect the polders against water levels due extreme river dis-
charges. The flooding of the flood plains increases the drainage capacity of the river and
reduces the local water level gradients.

In a numerical model, the process of drying and flooding is represented by removing grid
points from the flow domain that become dry when the tide falls and by adding grid points
that become wet when the tide rises. Drying and flooding is constrained to follow the sides of
grid cells. In this section, we specify the algorithms which have been used to determine the
moment when a grid cell (water level point) or cell boundary (velocity point) becomes dry or
wet. Drying and flooding gives a discontinuous movement of the closed boundaries and may
generate small oscillations in water levels and velocities. The oscillations introduced by the
drying and flooding algorithm are small if the grid sizes are small and the bottom has smooth
gradients.

Essential elements of the wetting and drying algorithm are the definition of the water level, the
definition of the bed level and the criteria for setting a velocity and/or water level point wet or
dry. In the following subsections, these three items will be discussed.

22.5.1 Dry/wet criterion at cell faces

The parameter εhu (c.f. Epshu Table A.1) describes the threshold depth at cell faces. When
the water depth at cell faces exceeds this (hu > εhu ) value the cell is considered wet and
otherwise it is dry.

Deltares 325 of 562

 Numerical aspects of D-Flow Flexible Mesh

22.5.2 Dry/wet criterion at cell circumcenters

A research keyword TestDryingFlooding (Table A.1) is available for determining if the
water depth is positive at cell circumcenters. To compute this, a variable dtrsh is introduced
and when the water depth exceeds this value a cell is considered to be wet (h > dtrsh ).

The default value is TestDryingFlooding = 0 (D-Flow FM), and considers the thresh-
old for positivity as dtrsh = 0. Option 1 is the Delft3D 4 default:
dtrsh = max(10−9 , min(εhu , 10−3 )).
The last option 2 sets (dtrsh = 0) and furthermore considers a minimum volume for the trans-

T
port solver based on the product of εhu and the flow cell area. The last setting is introduced to
improve the stability of the transport computations, and can be activated if the default option
AF leads to instabilities in the constituents.

22.6 Advection at open boundaries

In hydrodynamic models, it is common practice to apply high-resolution grids in domains of
limited extent, for instance to investigate the influence of a dam design on local flow patterns
in a coastal area. Then, the challenge is to prescribe appropriate boundary conditions for
such a detailed model. Tidal motion is often important and therefore water levels have to
be prescribed. If an overall model with good reproduction of water levels and velocities is
available, then it is common practice to start with water levels from the overall model on the
open alongshore boundary and on both cross-shore boundaries of the detail model. Then,
often the reproduction of water levels is accurate, but the reproduction of flow velocities might
be less accurate. In particular, the residual flow velocities might be inaccurate. Obtaining
DR

a good velocity reproduction by prescribing only water levels often only works for the larger
models (e.g. > 30 km) so that bed friction, pressure gradient and acceleration can balance
each other. In smaller models, however, this might not be the case. Even small water level
differences on the open boundaries may introduce unrealistic high or low velocities. A remedy
might be to apply velocity boundaries or other types of boundary conditions (Neumann-type,
. . . ) on the cross-shore boundaries. However, this often reduces reproduction quality of water
levels or might introduce strange flow patterns. Also the existence of stratification may also
lead to unrealistic currents near open boundaries.

Therefore, in D-Flow FM the keyword Zerozbndinflowadvection can be activated in

order to suppress unphysical currents near open boundaries. This applies for all water level
open boundaries. This keyword has to be specified in group [numerics] and the options are
Zerozbndinflowadvection=0,1 or 2. A value of 0 results into the default Neumann
approach for currents, yielding that the gradient in velocity at the open boundary is zero. This
approach is the default and applied when keyword Zerozbndinflowadvection is not
specified. Applying a value of 1 forces cell center velocities to zero on the open boundary at
inflow for all water level boundaries. A value of 2 forces cell center velocities to zero on the
open boundary for both inflow and outflow for all water level boundaries.

Another option is to apply a so-called advection boundary, which can be specified via key-
word uxuyadvectionvelocitybnd as part of the boundary conditions in the ext-file;
see Section C.6.3. For this option, both the x- and y -components of the velocity vector at
the boundary have to be specified in the boundary condition file, in bc format (.bc). To be
more precise, one needs to prescribe the x- and y -components of the velocity vector in the
circumcenter of the virtual boundary cells (outside the domain boundary). It is not necessary
to rotate these components in the direction normal to some local boundary. They are from
West to East and from South to North components. An advection boundary is only applied at
inflow. At outflow, a Neumann-type approach is applied.

Deltares 326 of 562

 Numerical aspects of D-Flow Flexible Mesh

22.7 Artificial mixing due to sigma-coordinates

The σ -transformation is boundary-fitted in the vertical. The bottom boundary and free surface
are represented smoothly. The water column is divided into the same number of layers inde-
pendent of the water depth. In a σ -model, the vertical resolution increases automatically in
shallow areas.

For steep bottom slopes combined with vertical stratification, σ -transformed grids introduce
numerical problems for the accurate approximation of horizontal gradients both in the baro-
clinic pressure term and in the horizontal diffusion term. Due to truncation errors artificial

T
vertical mixing and artificial flow may occur, Leendertse (1990) and Stelling and Van Kester
(1994). This artificial vertical transport is sometimes called "creep".

Let zb be the position of the bed and H the total water depth. If we consider the transformation
from Cartesian co-ordinates to σ co-ordinates, defined by:
AF x = x∗ , y = y ∗ , σ =
z − zb
H
(H = ζ − zb ) (22.1)

as result σ = 0 at the bed level and σ = 1 at the free surface. The horizontal pressure
gradient reads:

∂p∗ ∂x∗ ∂p∗ ∂σ ∂p∗ ∂p∗

 
∂p 1 ∂zb ∂H
= ∗
+ = ∗
− +σ . (22.2)
∂x ∂x ∂x ∂σ ∂x ∂x H ∂x ∂x ∂σ
In case of vertical stratification near steep bottom slopes, small pressure gradients at the
left-hand side may be the sum of relatively large terms with opposite sign at the right-hand
side.
DR

Small truncation errors in the approximation of both terms result in a relatively large error in
the pressure gradient.

This artificial forcing produces artificial flow.

The truncation errors depend on the grid sizes ∆x and ∆z .

Observations of this kind has led to the notion of "hydrostatic consistency", see also Fig-
ure 22.13. In the notation used by Haney (1991) this consistency relation is given by:

σ ∂H ∂σ
< (22.3)
H ∂x ∂x

Figure 22.13: Example of a hydrostatic consistent and inconsistent grid; (a) Hδσ >
σ ∂H ∂H
∂x δx, (b) Hδσ < σ ∂x δx

Deltares 327 of 562

 Numerical aspects of D-Flow Flexible Mesh

From this equation, it can be seen that by increasing the number of σ -levels the consistency
condition will eventually be violated.

Similarly, for the horizontal diffusion term, the transformation from Cartesian co-ordinates to
σ co-ordinates leads to various cross derivatives. For example, the transformation of a simple
second order derivative leads to:
2
∂ 2c ∂ 2 c∗ ∂ 2 c∗ ∂ 2 c∗ ∂ 2 σ ∂c∗

∂σ ∂σ
= + − + 2 − + − (22.4)
∂x2 ∂x∗2 ∂x ∂σ 2 ∂x ∂x∗ ∂σ ∂x2 ∂σ

T
For such a combination of terms it is difficult to find a numerical approximation that is stable
and positive, see Huang and Spaulding (1996). Near steep bottom slopes or near tidal flats
where the total depth becomes very small, truncations errors in the approximation of the
horizontal diffusive fluxes in σ -co-ordinates are likely to become very large, similar to the
horizontal pressure gradient.
AF
DR

Figure 22.14: Finite Volume for diffusive fluxes and pressure gradients

Figure 22.15: Left and right approximation of a strict horizontal gradient

In D-Flow FM the stress tensor is redefined in the σ co-ordinate system assuming that the
horizontal length scale is much larger than the water depth (Mellor and Blumberg, 1985) and

Deltares 328 of 562

 Numerical aspects of D-Flow Flexible Mesh

that the flow is of boundary-layer type. The horizontal gradients are taken along σ -planes.
This approach guarantees a positive definite operator, also on the numerical grid (Beckers
et al., 1998).

If the same approach is used for the horizontal diffusion operator in the transport equation:

∂ 2c ∂ 2 c∗
≈ (22.5)
∂x2 ∂x∗ 2
Horizontal diffusion will lead to vertical transport of matter through vertical stratification inter-

T
faces (pycnocline) which is nonphysical. A more accurate, strict horizontal discretization is
needed.

In D-Flow FM an option is available that minimises artificial vertical diffusion and artificial flow
due to truncation errors. A method has been implemented which gives a consistent, stable and
AF
monotonic approximation of both the horizontal pressure gradient and the horizontal diffusion
term, even when the hydrostatic consistency condition equation is not fulfilled. This "anti-
creep" option is based upon a Finite Volume approach; see Figure 22.14. The horizontal
diffusive fluxes and baroclinic pressure gradients are approximated in Cartesian co-ordinates
by defining rectangular finite volumes around the σ -co-ordinate grid points. Since these boxes
are not nicely connected to each other, see Figure 22.15, an interpolation in z co-ordinates is
required to compute the fluxes at the interfaces.

Since the centres of the finite volumes on the left-hand side and right-hand side of a vertical
interval are not at the same vertical level, a z -interpolation of the scalar concentration c is
needed to compute strictly horizontal derivatives. The values obtained from this interpolation
DR

are indicated by c∗1 and c∗2 respectively in Figure 22.15. (Stelling and Van Kester, 1994) apply
a non-linear filter to combine the two consistent approximations of the horizontal gradient,

s1 = (c∗2 − c1 ) /∆x and s2 = (c2 − c∗1 ) /∆x

If s1 × s2 < 0 Then
∆c
∆x
=0
(22.6)
Else
∆c
∆x
= sign (s1 ) × min (|s1 | , |s2 |)
Endif

If an interval has only grid boxes at one side, the derivative is directly set to zero. The hor-
izontal fluxes are summed for each control volume to compute the diffusive transport. The
integration of the horizontal diffusion term is explicit with time step limitation:
 
1 1 1
∆t ≤ + (22.7)
DH ∆x2 ∆y 2
The derivatives are used in the integral for the baroclinic pressure force in the momentum
equation:
Z ζ
1 ∂ρ (x, s)
Px (x, z) = g ds (22.8)
ρ0 z ∂x
Originally, this approach was implemented in Delft3D-FLOW. Slørdal (1997) stated that the
above approximation may sometimes produce errors of the same sign which leads to a sys-
tematic underestimation of the baroclinic pressure term. This underestimation can be ascribed
to the non-linear filter, which selects the minimum of the two gradients under consideration.

Deltares 329 of 562

 Numerical aspects of D-Flow Flexible Mesh

This limiter is fully analogous to the min-mod limiter used for the construction of monotone
advection schemes (Hirsch, 1990). Since the same approximation of the horizontal gradient
is used for the horizontal diffusion flux, it is important to ensure that the difference operator
is positive definite in order to get physically realistic solutions. The maximum and minimum
of a variable being transported by diffusion do not increase or decrease (min-max principle).
By taking the minimum of the gradients, Stelling and Van Kester (1994) show that, the min-
max principle is fulfilled. Beckers et al. (1998) show that any nine-point consistent linear dis-
cretization of the horizontal diffusion on the σ -grid does not fulfil the min-max principle. From
numerical tests Slørdal (1997) concluded that the underestimation is reduced by increasing
the vertical resolution, but is sometimes enhanced by increasing the horizontal resolution.

T
Let s4 be a consistent approximation of the horizontal gradient s4 = (s1 + s2 )/2. Slørdal
(1997) suggested to take s4 as approximation of the horizontal gradient. He calls his approach
the "modified Stelling and Van Kester scheme". It is equivalent to linear interpolation at a
certain z -level before taking the gradient. It is more accurate than taking the minimum of
AF
the absolute value of the two slopes s1 and s2 but it does not fulfil the min-max principle
for the diffusion operator. It may introduce wiggles and a small persistent artificial vertical
diffusion (except for linear vertical density distributions). Due to the related artificial mixing,
stratification may disappear entirely for long term simulations, unless the flow is dominated by
the open boundary conditions.

By introducing an additional approximation of the horizontal gradient in the filter algorithm

defined by s3 = (c2 − c1 )/∆x, the stringent conditions of the minimum operator can be re-
laxed somewhat. The drawback of underestimation of the baroclinic pressure force reported
by Slørdal (1997) can be minimised without loosing that the method fulfils the min-max princi-
ple. This third gradient s3 , which is consistent for min(|s1 | , |s2 |) < s3 < max(|s1 | , |s2 |),
DR

has point-to-point transfer properties and therefore leads to a positive scheme for sufficiently
small time steps. The following non-linear approach presently available in D-Flow FM is both
consistent and assures the min-max principle:

If s1 × s2 < 0 Then
∆c
=0
∆x
Elseif |s4 | < |s3 | Then
∆c
∆x
= s4
Elseif min (|s1 | , |s2 |) < |s3 | < max (|s1 | , |s2 |) Then (22.9)
∆c
∆x
= s3
Else
∆c
∆x
= sign (s1 ) min (|s1 | , |s2 |)
Endif

The method requires a binary search to find the indices of neighbouring grid boxes, which is
time consuming. The increase in computation time is about 30 %.

If the streamlines are strictly horizontal, transport of matter discretised on a σ co-ordinate

grid may still generate some numerical vertical diffusion by the discretisation of the advection
terms.

Deltares 330 of 562

 23 Tutorial
This chapter includes a number of basic tutorials on setting up and running a hydrodynamic
simulation with D-Flow FM 2D3D. Different functionalities of this module will be discussed
in the upcoming exercises. In each exercise, a step-by-step approach is used to set-up a
different type of model. Each model that is created is a hypothetical model with randomly
chosen dimensions and parameters.

However, before you start with these tutorials, it is important to learn some basic grid concepts,
which have been described in Section 22.1.

T
Note: in this chapter, read for Delft3D Flexible Mesh Suite either “D-HYDRO Suite” or
“Delft3D Flexible Mesh Suite”.
AF
23.1

23.1.1
Tutorial Hydrodynamics for depth-averaged (2D) modelling

Outline of the tutorials

In this three-hours tutorial you will experience the basic functionality of D-Flow FM. On the
one hand you will learn how to capture a certain area with a computational grid. On the other
hand you will set up and run a computation yourself. This involves for example inserting a bed
level, imposing boundary conditions, running a D-Flow FM model and postprocessing with a
D-Flow FM output file. This manual contains nine tutorials (with indication of the estimated
time):
⋄ Tutorial 1 (section 23.1.2): Creating a curvilinear grid (25 minutes).
DR

⋄ Tutorial 2 (section 23.1.3): Creating a triangular grid (20 minutes).

⋄ Tutorial 3 (section 23.1.4): Coupling multiple distinct grids (15 minutes).
⋄ Tutorial 4 (section 23.1.5): Inserting a bed level (15 minutes).
⋄ Tutorial 5 (section 23.1.6): Imposing boundary conditions (25 minutes).
⋄ Tutorial 6 (section 23.1.7): Defining output locations (15 minutes).
⋄ Tutorial 7 (section 23.1.8): Defining computational parameters (10 minutes).
⋄ Tutorial 8 (section 23.1.9): Running a model simulation (20 minutes).
⋄ Tutorial 9 (section 23.1.10): Viewing the output of a model simulation (15 minutes).

The necessary input files for a tutorial can be found in the folders tutorial01 through tutorial09.
When saving your model data while working through these tutorials, be sure not to overwrite
the tutorial data. Ideally, you should create a separate working folder somewhere else on your
computer to save your work. The folder finished in each tutorial folder contains the output
generated by Deltares as a reference.

We will use the Western Scheldt and the harbour of Antwerp as an example case for gener-
ating a grid and for setting up and running a computation.

Deltares 331 of 562

 Tutorial

23.1.2 Tutorial 1: Creating a curvilinear grid

Generating grids is done with the RGFGRID tool. Because this is an iterative process and
the Undo functionality in RGFGRID is still rather limited, it is important to frequently save
intermediate RGFGRID results. By clicking on Esc it is sometimes possible to undo the last
action. RGFGRID is a separate tool that communicates with the Delft3D Flexible Mesh Suite
GUI through a temporary folder whose path is shown in the top menu bar. In order to transfer
the generated grid to the Delft3D Flexible Mesh Suite GUI, be sure to save your data to this
path when leaving RGFGRID.

T
To start RGFGRID in the Delft3D Flexible Mesh Suite Graphical User Interface the following
steps have to be carried out:
Double click on the Delft3D Flexible Mesh Suite icon on the desktop of your computer.
Click on New Model in the main toolbar at the top of the Delft3D Flexible Mesh Suite GUI.
A new window pops up in which you have to select Flow Flexible Mesh Model → OK.
AF Double click on Grid, see Figure 23.1. RGFGRID will now start.
DR

Figure 23.1: Start RGFGRID by a double-click on Grid.

Choose from the main menubar Coordinate System → Cartesian Coordinates. This is
the default setting, which means that you do not have to change anything.

A curvilinear grid is iteratively generated by first drawing splines. The approach is as fol-
lows:deltashe

Import a land boundary via File → Attribute Files → Open Land Boundaries and select
the file <tutorial01\scheldtriver.ldb>
Select Edit → Splines → New and draw a spline roughly following the left boundary of
the river (use the leftmousebutton). Finalise the spline by one rightmouseclick.
Now we want to bring (attach) the spline close to the boundary.
Choose the option Edit → Splines → Attach to Land Boundary. Select the the two outer
points delimiting the spline to be snapped. The vertices which will be snapped are now
marked by a square. Press the rightmousebutton to perform the snapping.
A window appears for extra snapping: Press Yes several times. You will see the spline
evolve towards the land boundary. Press No when you are satisfied with the result.
Repeat the previous three steps for the righthandside spline.
Draw a third spline along the river axis; see Figure 23.2.

Deltares 332 of 562

 Tutorial

T
AF
Figure 23.2: Splines in Tutorial01

Draw two cross-splines, each containing exact two vertices: one spline at the North side
and one spline at the South side of the river (see Figure 23.2). The channel is now
enveloped by four splines and there is an extra spline along the river axis.
Now we can grow a grid from these splines.
Choose Settings → Grow Grid from Splines. . . . You will be able to set several settings
for this process. Take over the values shown in Figure 23.3.
DR

Figure 23.3: Settings for the Grow Grid from Splines procedure.

A brief explanation:
⋄ Using the parameter Max. num. of gridcells perp. in uni. part, the user can give an
indication of the number of cells across the width between the longitudinal splines.
⋄ By using the parameters Maximum grid length along center spline, the user can give
an indication of the length of the cells in longitudinal direction. Based on the value
of the parameter Aspect ratio of first grid layer, the algorithm establishes a suitable

Deltares 333 of 562

 Tutorial

grid, under the restrictions of the prevailing maximum numbers of gridcells (first two
entries).
⋄ The option Grid layer height growth factor enables the user to demand for a non-
equidistant grid in cross-sectional direction. The value represents the width-ratio of
two adjacent cells. Using the option Grow grid outside first part (0/1), one can extend
a grid outside the longitudinal splines, for instance to capture winterbed regions.

After entering the values of Figure 23.3, choose Operations → Grow Grid from Splines.
This will deliver the grid as shown in Figure 23.4.

T
AF
DR

Figure 23.4: Generated curvilinear grid after the new Grow Grid from Splines procedure.

To be able to further improve the grid, choose Operations → Convert grid → Regular to
Irregular. Strictly, the grid is now not curvilinear anymore, but unstructured.
Choose View → Grid Property Style → Coloured Edge and then View → Grid Property
→ Orthogonality. The result is shown in Figure 23.5. We remark that no orthogonalisation
iterations have been performed yet. Try to reach the level of orthogonality as shown in
Figure 23.5. By clicking on Menu option Operations →Orthogonalize the orthogonality
can be improved.

Deltares 334 of 562

 Tutorial

T
AF
Figure 23.5: Orthogonality of the generated curvilinear grid after the Grow Grid from
DR

Splines procedure.

To save the grid and close RGFGRID the following steps have to be carried out:

Choose from the menubar File → Export → UGRID (D-Flow FM). . . and save the grid in
your working folder as <tutorial01\scheldt01_net.nc>. The grid has now been saved.
Choose File → Attribute Files → Save splines with Intermediate Points and save the
splines in your working folder as <tutorial01\scheldt01.spl>. The splines have now
also been saved.
Choose File → Save Project. Press Cancel when a file selection box asks to save the
land boundary.
Close RGFGRID by choosing File → Exit

Folder <tutorial01\finished> contains splines and a grid for this tutorial exercise that has been
prepared by Deltares.

Now you are back in the Delft3D Flexible Mesh Suite GUI. As you can see only the grid has
been imported from RGFGRID. If you want to see the land boundary here too, you need to
import it:

Open Area under Project1 →FlowFM →Area.

Import the land boundary from <tutorial01\scheldtriver.ldb> by choosing Import via the
right mouse button on Project1 →FlowFM →Area →Land Boundaries (see Figure 23.6).
Do not apply a coordinate transformation by pressing OK.

Deltares 335 of 562

 Tutorial

T
Figure 23.6: Importing a land boundary
AF Now the grid and land boundary are both visible in the central map of the Delft3D Flexi-
ble Mesh Suite GUI, see Figure 23.7.
DR

Figure 23.7: After closing RGFGRID the grid is visible in the Delft3D Flexible Mesh Suite
GUI.

This is the end of Tutorial 1.

To close the Delft3D Flexible Mesh Suite, click on File → Close. Then, the following
question arises: "Save changes to the project: Project?" Click on No. The current D-
Flow FM model has now been closed.
Exit the Delft3D Flexible Mesh Suite by choosing the close icon ( ) in the windows title
bar.

23.1.3 Tutorial 2: Creating a triangular grid

We will continue with the grid created in the previous tutorial for the Scheldt river. The river is
separated from the harbour, west of the river, by a sluice. The small area between the sluice

Deltares 336 of 562

 Tutorial

and the Scheldt will benefit from an unstructured grid because of its irregular geometry. The
unstructured grid for this irregular geometry is created first in this section.

The following steps have to be carried out:

Start the the Delft3D Flexible Mesh Suite and create a new Flow Flexible Mesh Model as
described in section 23.1.2.
Import the land boundary from <tutorial02\scheldtharbour.ldb> by choosing Import via
the right mouse button on Project1 →FlowFM →Area →Land Boundaries (see Fig-
ure 23.6). Select item Land boundaries from .ldb file and press OK. Select the file
<scheldtharbour.ldb> with the file selection window. Do not apply a coordinate trans-

T
formation, press OK.
Import the grid file by choosing Import via the right mouse button on Project1 →FlowFM
→Grid. Choose the grid file <scheldt02_net.nc> in the folder <tutorial02>.
Start RGFGRID by double clicking on Grid, see Figure 23.1. Set the Coordinate System
AF
(if necessary), as has been explained in section 23.1.2 (Figure 23.1).
Choose from the menubar Edit → Polygons → New. The intention is to mark the area of
interest (i.e. the area for which we want to generate the grid) by means of a polygon, see
Figure 23.8.
Start drawing the polygon at a distance from the curvilinear grid that is similar to the width
of the curvilinear grid cells (since we want to have a smooth transition in grid resolution).
Specify the second point at a relatively small distance from the first one. This distance is
later used as the first indication of the size of the triangular gridcells to be placed.
Mark the characteristic locations of the area (follow the land boundary) and place the
final points at the same distance away from the river grid as the first point. The distance
between the last two points should be similar to the distance between the first two points.
DR

The result is shown in Figure 23.8.

Choose Edit → Polygons → Refine (linear) and click on the first and last points of the
polyline (in Figure 23.8 we would select point 1 first and then point 15). Now, the polygon
is divided into a finer set of line elements (based on the length of the first and last segment
of the polyline).

Figure 23.8: Polygon that envelopes the area in which an unstructured grid is aimed to
be established.

Remarks:

Deltares 337 of 562

 Tutorial

⋄ The distance between the points of the polygon is derived from the distance of the
two polyline segments at both sides of the selected segment. The length of the poly-
line segments varies linearly from the segment length at the one side of the selected
segment towards the segment length at the other side of the selected segment.
⋄ You can play around to see how this works. If needed, you can add extra polyline
points by choosing Edit → Polygon → Insert point. Choose Edit → Polygon →
Move point if a point move would make sense.
⋄ You can snap the refined polygon to the land boundary through Edit → Polygons →
Attach to Land Boundary. Select two points for this.
Now we continue with this tutorial by carrying out the following steps:

T
Choose Operations →Domain →New to indicate that the new to be generated grid should
be created next to the already existing one (and not replace it).
Choose Operations → Grow Grid from Polygons. The result is shown in Figure 23.9.
Improve the orthogonality through Operations → Orthogonalise grid. The default settings
are set to also improve the smoothness.
AF
Since the solver only supports one grid, we need to merge the newly created grid with the
original grid of the river. The newly created grid is currently selected. Next:

Choose Edit →Multi Select and click on the river Scheldt grid to select it as well. After
selection both grids should be coloured blue with black dots on the nodes.
Choose Operations →Grid →Merge Grids to merge the nodes of the (two) highlighted
grids. Now, the grids have been merged. However, nothing will visually change.
DR

Figure 23.9: Unstructured grid, after having refined the polygon.

To save the grid and go back to the Delft3D Flexible Mesh Suite GUI:

Choose from the menubar File → Export → UGRID (D-Flow FM). . . and save the grid in
your working folder as <tutorial02\scheldt02_net.nc>. Both grids grids have now been
merged into one <.nc> file.
Choose File → Save Project As and save the project in your working folder. Press Cancel
when a file selection box asks to save the land boundary. Press Cancel twice when a file
selection box asks to save the grid.

Deltares 338 of 562

 Tutorial

Close RGFGRID by choosing File → Exit

Now you are back in the Delft3D Flexible Mesh Suite GUI but the grid is not yet updated in the
D-Flow FM model. Therefore finalyse this tutorial as follows:

Choose Import by a right mouse click on Project1 → FlowFM → Grid and select the grid
file <scheldt02_net.nc> in your working folder.
Exit Delft3D Flexible Mesh Suite by clicking the close icon in the menu bar. You don’t have
to save the project.

T
This is the end of Tutorial 2.

Folder <tutorial02\finished> contains splines and a grid for this tutorial exercise that has been
AF prepared by Deltares.

23.1.4 Tutorial 3: Coupling multiple separate grids

From the previous tutorial we have ended up with two separate grids that are not connected
yet. Obviously, these two grids should properly be integrated into one single grid. Before we
can couple the two grids, we should first make sure that the typical grid size is of the same
order of magnitude for both grids at the location where the connection is to be laid. Hence,
basically two operations are to be done:
⋄ Split the grid cells in the Scheldt river along this length so that the cell sizes of both grids
match.
⋄ Merge the two grids and put connections in between.
DR

The splitting can be established as follows:

Start the the Delft3D Flexible Mesh Suite and create a new Flow Flexible Mesh Model as
described in section 23.1.2.
Import the land boundary file and the grid file from the folder <tutorial03> as described
in section 23.1.3.
Start RGFGRID and set the Coordinate System (if necessary), as has been explained in
section 23.1.2 (Figure 23.1).
Choose Edit → Irregular Grid → Split Row or Column.
Select the locations where the grid lines should be split by clicking on the left boundary of
the Scheldt river.
Try to achieve the picture shown in Figure 23.10, in particular the typical grid size in the
curved area. N.B. Ignore the red lines in this picture for now!

Deltares 339 of 562

 Tutorial

T
AF
Figure 23.10: Connection of the river grid and the unstructured grid. The red lines show
the inserted grid lines used to couple the two grids manually.

The edges of the two the grid segments can be connected as follows:

Since the two visually separated grids have already been merged into one logical grid in
DR

the previous tutorial, we can now physically connect them by laying new gridlines between
them. Therefore, select Edit → Irregular Grid → Insert Node. Insert new gridlines in a
zigzag-like style: see the red grid lines in Figure 23.10. Now, you will benefit from the
(more or less) equal resolutions in the river and unstructured regions.
Finally, you will end up with a picture like shown in Figure 23.11. You can visualize the
orthogonality through View → Grid Property Style → Coloured Edge and View → Grid
property → Orthogonality.

Deltares 340 of 562

 Tutorial

T
AF
Figure 23.11: Orthogonality of the integrated grid, containing the curvilinear part, the tri-
angular part and the coupling between the two grids.

To save the grid and close RGFGRID is done as follows:

File → Export → UGRID (D-Flow FM). . . and save the grid to your working folder as
DR

<tutorial03\scheldt03_net.nc>.
The grid has now been saved.
Choose File → Save Project.
Close RGFGRID by clicking on Exit.

This is the end of Tutorial 3.

Exit Delft3D Flexible Mesh Suite by clicking the close icon in the menu bar. You don’t have
to save the project.

23.1.5 Tutorial 4: Inserting a bed level

In previous tutorial exercises we focused on the grid generation. The next step is to couple the
bed level data to the grid. The grid for this tutorial exercise is available in file <westernscheldt04_net.nc>
in the directory <tutorial04>. A harbour has been added to the grid, as well as the Western-
scheldt part at the North side. Bed levels are available in the file <westernscheldt_bed_level.xyz>.

The file with bed levels should first be projected onto the unstructured grid by means of inter-
polation. To this purpose, the following actions should be carried out:
Start Delft3D Flexible Mesh Suite, create a new Flow Flexible Mesh model, import the
land boundary <sealand.ldb> and the grid <westernscheldt04_net.nc> from directory
<tutorial04> as explained in the previous tutorial exercises.
Import a sample file containing the measured bed levels: in the drop down menu at the
top of the screen (See Figure 23.12), select the Spatial Operators menu, choose layer Bed
Level, click on Import from file and select the file <westernscheldt_bed_level.xyz>
from directory <tutorial04>, Import without transformation (as-is) → OK. This file con-
tains measured bed level data for the Westernscheldt, from the North Sea up to Antwerp

Deltares 341 of 562

 Tutorial

Figure 23.12: Map-ribbon with the Spatial Operations menu.

T
AF
Figure 23.13: Activate import samples 1.

Now we are going to project the bed level data onto the nodes:
Click on Operations and click on "Import samples 1"; see Figure 23.13.
Click and select Interpolate selected set (see Figure 23.12).
The window Interpolation operation appears. Select the Overwrite option for Pointwise
DR

operation, then press OK. The result will look like Figure 23.14. If you do not see a color

bar, click Legend in the Decorations menu (see Figure 23.12) and switch off items
in the Map pane to bring the color bar into view.

Figure 23.14: Interpolated bed levels values at the grid (estuary).

Have a look at the sluice and the docks of the harbour. You can see that the bed level in this
area is unrealistically high. This unrealistic value has been assigned because of undesired

Deltares 342 of 562

 Tutorial

extrapolation, since no bed level data has been available in this area. To repair this, first
draw a polygon that envelops the sluice and the docks. Do this by clicking Draw
polygon (see Figure 23.12). Double-click to finish the polygon. See Figure 23.15.

T
AF
Figure 23.15: Polygon drawn to around the missing depths in the harbour.

Choose Set value (see Figure 23.12): specify an appropriate value, for instance
DR

“-10” m. The result will look like as shown in Figure 23.16.

Figure 23.16: Interpolated bed levels values at the grid (harbour).

Note: The mesh file (<∗_net.nc>) will contain the grid together with the bed level data at
the nodes.

To save the mesh and bed level, and save the model within the Delft3D Flexible Mesh Suite
GUI the following should be done:

Deltares 343 of 562

 Tutorial

To save the mesh file you have to rightmouseclick on Grid → Export in the project tree.
Choose Grid exporter and save the file in the folder <tutorial04> of your working en-
vironment as <westernscheldt04_net.nc>. The grid including the bed level have now
been saved.
To close the D-Flow FM User Interface click on File → Close. Then, the following question
arises: "Save changes to the project: Project?" Click on No.
Exit Delft3D Flexible Mesh Suite by clicking the close icon in the menu bar.

Folder <tutorial04\finished> contains a bed level for this tutorial exercise that has been pre-
pared by Deltares.

T
23.1.6 Tutorial 5: Imposing boundary conditions
Along both the sea boundary and the Scheldt river boundary, appropriate boundary conditions
have to be imposed. The boundary conditions can be prescribed in many ways, for instance
AF as water levels, velocities (tangential and normal direction), discharge and Riemann. In this
tutorial exercise we will impose boundary conditions for the Western Scheldt in the following
way:
⋄ At the sea boundary: a periodic water level boundary, described as a harmonic signal with
a mean 0.5 m+NAP, an amplitude 2.5 m and a frequency of 28.984 ° h−1 ,
⋄ At the river boundary: a constant discharge boundary, described by a constant 2500 m3 s−1 .

Let us start with a new D-Flow FM model and import the network and land boundaries:
Start Delft3D Flexible Mesh Suite, create a new Flow Flexible Mesh model, import the
DR

boundary <sealand.ldb> and the grid <westernscheldt05_net.nc> from directory <tutorial05>

as explained in the previous tutorial exercises.

In order to define boundary conditions one has to follow this strategy:

1 draw a polyline along the boundary;
2 fill a file with essential information;
3 link the boundary files with the model setup.

The boundary conditions can be imposed as follows:

In the FM Region. . . (in the top ribbon, see Figure 23.17) choose Add a (2D) flow
boundary and insert a polyline along the sea boundary. Doubleclick to finish the polyline.
In the Project bar at the left, under Boundary Conditions, this boundary has now been
added. Figure 23.17 shows how this will look like.
Tip: to remove a wrongly placed point in the polyline, use Remove point from geometry
(top of screen, above Edit, see Figure 23.17). It is also possible to replace or add a point.

Deltares 344 of 562

 Tutorial

T
AF
Figure 23.17: Location of the two open boundaries at the sea and river side.

Draw another polyline at the river entrance south of Antwerp, see the right bottom corner
of Figure 23.17).
To impose boundary conditions at the seaboundary, double click at Boundary01, see Fig-
ure 23.18.
DR

Figure 23.18: Selection of Boundary01.

Choose Water level, press + and choose Forcing type: Astronomical.

Selected the first boundary support point Boundary01_0001 by clicking on the plus-sign
behind it, repeat this for the last boundary support point.
Choose Select components. . . (at the lefthandside of the screen).
Choose the components A0 and M2, and press OK,
Select All support points and press OK. All support points will now have components A0
and M2 defined.
Fill in the amplitudes of the components in the table, see Figure 23.19.

Deltares 345 of 562

 Tutorial

T
AF
Figure 23.19: Boundary conditions seaside.

We have now prescribed an astronomical water level signal, consisting of two components.
The first component has an amplitude equal to 0.5 m with a frequency of 0 degrees/hour,
i.e. a constant value of 0.5 m+NAP. The second component has an amplitude of 2.5 m with
a frequency of 28.98 degrees/hour. Basically, the signal h(t) = 0.5 + 2.5 cos(28.98 t)
DR

has been prescribed now, with h in meters w.r.t. the reference level (in this case: NAP)
and t in hours.
To impose boundary conditions at the riverboundary, double click at Boundary02, Choose
Discharge and press +. Choose Forcing type: Time Series.
To impose a contant discharge of 2500 m3 s−1 , fill in the table as in Figure 23.20. Make
sure you insert the correct times!

Figure 23.20: Boundary condition riverside.

Deltares 346 of 562

 Tutorial

To be able to load this D-Flow FM model in the future, it is necessary to save the model:
In the project tree, rightclick on FlowFM and select Rename. Rename the model to “west-
ernscheldt05”.
Save the model in folder <tutorial05> of your working environment: in the project tree
rightclick on westernscheldt05. Choose Export select Flow Flexible Mesh model, press
OK and save the model as <westernscheldt05.mdu>.

The model can now be loaded in the next tutorial exercise without the need of inserting all
network files or land and flow boundaries individually again.

T
Exit Delft3D Flexible Mesh Suite by clicking the close icon in the menu bar. You don’t have
to save the project.

23.1.7 Tutorial 6: Defining output locations

AF Often one would like to monitor computational results at certain specific cross sections or
locations (i.e. ’observation points’). In this tutorial exercise we will add cross sections and
observation points in a D-Flow FM model.

We will start with importing an existing D-Flow FM model without cross sections and observa-
tion points:

Start Delft3D Flexible Mesh Suite and import a D-Flow FM Model by choosing (in the top
ribbon) Import → Flow Flexible Mesh Model.
Choose <westernscheldt06.mdu> from the folder <tutorial06> and click on Open.
DR

Inserting cross sections and observation points is rather straightforward. The following actions
are necessary:

Inserting cross sections:

Choose Add new observation cross section (2D) (see the Area menu in the ribbon).
Draw as many cross sections as you like. Finalize each cross section by doubleclicking
the left mouse button.
To see how many cross sections have been made, double click on Area → Observation
Cross-Sections in the project tree, see Figure 23.21.

Deltares 347 of 562

 Tutorial

T
AF
Figure 23.21: Overview cross sections and observation points.

Now we will add observation points:

Choose Add new observation point. Add as many observation points as you like.
To see how many observation points have been made, double click on Area → Observa-
DR

tion Points in the project tree.

Save the current FM model by clicking the right mouse in the project tree on western-
scheldt06.
Choose Export, choose Flow Flexible Mesh Model and press OK. Then save the model
with name “westernscheldt06” in the folder <tutorial06> of your working environment.
The observation points and cross sections have now been saved in the new <mdu>-file.
Tip: It is also possible to save only the observations points. For instance to a different
folder. To try this, click the right mouse on Observation points → Export → Observation
points to <xyn>-file. Then, choose a filename and a folder.
Exit Delft3D Flexible Mesh Suite by clicking the close icon in the menu bar. You don’t have
to save the project..

23.1.8 Tutorial 7: Defining computational parameters

Before we can run a model, all computational parameters need to be set. This involves for
example the Time Frame, Initial Conditions and the Output Parameters. Most parameters can
be set in parameter screens accessible through the project tree. All other parameters are set
by default, and will not be considered in this tutorial exercise.

We will start by importing an existing D-Flow FM model:

Start Delft3D Flexible Mesh Suite and import the D-Flow FM Model from the folder <tutorial07>,
by choosing Home → Import → Flow Flexible Mesh Model → OK. Choose <westernscheldt07.mdu>
and press Open.

Several parameters will be set. We will start with the Time Frame, see Figure 23.22:
At the Time Frame section: fill in the parameters shown in Figure 23.22.

Deltares 348 of 562

 Tutorial

T
Figure 23.22: The time frame of the simulation.

At the Initial Conditions section: fill in “0.5” m for the Initial water level, see Figure 23.23.
AF
Figure 23.23: Imposed initial conditions for the simulation.

At the Output Parameters section: fill in the parameters shown in Figure 23.24.
DR

Figure 23.24: Optional output parameters for the computation.

As an explanation, the computation will generate history-files and map-files:

⋄ In history-files, timeseries are stored at the cross-sections and observation locations, at a
frequency specified via the parameter His Output Interval.
⋄ The map-files collect data over the entire domain, at a frequency specified via the param-
eter Map Output Interval.
Note: Be aware that these periods are clipped by the parameter User time step, which has
been specified under Time Frame. That means, if User time step > His Output Interval,
then the period with which his-files are written is given by User time step.
⋄ Restart files will be written when Write Rst File is selected.

Deltares 349 of 562

 Tutorial

The period with which these files are written can then be specified at Rst Output Interval.
This period is not clipped by User time step. To start a computation with a restart file is
not part of this tutorial.

Save the current D-Flow FM model in the folder <tutorial07> of your working environ-
ment by rightmouseclicking in the project tree on westernscheldt07, choose Export and
save the model as Flow Flexible Mesh model <westernscheldt07.mdu>.

The computational parameters have now been saved in the <mdu>-file.

Exit Delft3D Flexible Mesh Suite by clicking the close icon in the menu bar.

T
23.1.9 Tutorial 8: Running a model simulation
Up till now we have saved the D-Flow FM model by means of a <mdu>-file. For running
computations, it is necessary to save the entire project, which will be done in this tutorial
AF exercise:

Import the D-Flow FM Model from the folder <tutorial08>, by choosing Import → Flow
Flexible Mesh Model → OK. Choose <westernscheldt08.mdu> and Open.

For saving the entire project, the following should be done:

Choose File → Save As to save <tutorial08.dsproj> in the folder <tutorial08> of your
working environment and click Save.
The project has now been saved in a folder called <tutorial08\tutorial08.dsproj_data>
and a project file <tutorial08\tutorial08.dsproj> has been created (See Figure 23.25).
DR

Within this folder you will find all input files of the model (some are ASCII), output files of
the model (when it has been run) and, if applicable, zip-folders containing the restart files.
Note that after saving, the project has been renamed to tutorial08

Figure 23.25: Menu for saving a project.

To start a computation, the following needs to be done:

In the project tree select the model you want to run (which has been named western-
scheldt08, see Figure 23.26).

Deltares 350 of 562

 Tutorial

Press the right mouse and choose Run Model

The simulation will now start running.

T
AF
Figure 23.26: View of Delft3D Flexible Mesh Suite when running a model.
DR

Now:
Save the project with generated output in the folder <tutorial08> of your working envi-
ronment (File → Save As and save the project with name “tutorial08.dsproj”). Press Yes
to overwrite the project.
Now close the current D-Flow FM model (In the project bar, rightmouseclick on western-
scheldt08 → Delete → OK ).
Exit Delft3D Flexible Mesh Suite by clicking the close icon in the menu bar.

Folder <tutorial08\finished> contains the output for this tutorial exercise that has been pre-
pared by Deltares.

23.1.10 Tutorial 9: Viewing the output of a model simulation

The output of the model can be observed within Delft3D Flexible Mesh Suite. At first a project
has to be imported:
Choose File → Open. Select the file <tutorial9.dsproj> from the folder <tutorial09> and
choose Open. The project is now activated.
Doubleclick on westernscheldt09.

To view the output of the history files (observation points and cross-sections):
Click with leftmousebutton on an observation point (while being in select mode. Your
mouse looks like an arrow in this mode).
Choose at the top part of the screen Query Time Series, see Figure 23.27 (option available
within the Map-ribbon).

Deltares 351 of 562

 Tutorial

T
AF
Figure 23.27: View of Delft3D Flexible Mesh Suite, available to select a location for time-
series in.

Choose Water level (waterlevel) → OK. You can now observe the water levels in the
observation point you selected, see Figure 23.28. You can choose other parameters as
well to observe. Also cross-sections can be observed this way.
Select the Time Navigator in the View section of the ribbon. The Time Navigator will
DR

appear at the bottom of Delft3D Flexible Mesh Suite.

Figure 23.28: View of Delft3D Flexible Mesh Suite, time-series for observation point ”wa-
ter level at Borsele”.

To view the output of the map files:

Select the pane ’westernscheldt09’
Choose in the Map-tree Add New Wms Layer (see Figure 23.29) and choose <Open
Street Map>.

Deltares 352 of 562

 Tutorial

Figure 23.29: WMS layer icon at the top of the map-tree viewer.

Now, the model can be observed with OpenStreetMap in the background. See Fig-
ure 23.30.

T
AF
DR

Figure 23.30: View of Delft3D Flexible Mesh Suite in combination with OpenStreetMap.

Open Output in the map tree. Check waterlevel(s1) to observe water levels, see Fig-
ure 23.31.

Figure 23.31: Select waterlevel(s1) from the map tree

To adjust the legend, rightmouseclick on Output(map) →waterlevel (s1) and select Prop-
erties. Now the window Layer Properties Editor appears in which the legend can be
adjusted.
Set classes to “11”
Select Custom range and set the legend values for minimum and maximum value to “-2.5”
to “-0.5”.
Press Generate
Press OK, see Figure 23.32.

Deltares 353 of 562

 Tutorial

T
AF Figure 23.32: Layer properties editor

Click the play button in the Time Navigator to see the water levels change in time. To see
the water depths, uncheck the water level in the map tree and check the water depth.
Now close the current D-Flow FM model (In the project bar, rightmouseclick on western-
scheldt09 → Delete → OK ).
Exit Delft3D Flexible Mesh Suite by clicking the close icon in the menu bar.

23.1.11 Tutorial 10: Exporting a model

DR

A model must be exported to be able to run it outside D-Flow FM GUI, see section 8.3.

Import the D-Flow FM Model from the folder <tutorial10>, by choosing Import → Flow
Flexible Mesh Model → OK. Choose <westernscheldt10.mdu> and Open.

To export:
Rightmouseclick on Westernscheldt10 in the project view on the left. Choose Export →
DIMR configuration → OK, see Figure 23.33. Select an empty directory to store the
resulting files, <tutorial10\workdir>, and choose a name for the DIMR configfile, default
<dimr_config.xml>. Directory <tutorial10\workdir> will now contain file <dimr_config.xml>
and subdirectory <dflowfm>. Besides some cleaning, the files inside subdirectory <dflowfm>
should be the same as in <tutorial10\input>.

Deltares 354 of 562

 Tutorial

T
AF
Figure 23.33: Menu for exporting a project.

Folder <tutorial10\output> contains the output for this tutorial exercise that has been pre-
pared by Deltares. Differences may appear related to changes in execution date and time,
DR

and using another version of the GUI.

23.1.12 Tutorial 11: Partitioning a model

A model must be partitioned before it can be run in parallel by using MPI, see section 8.4.2.
You can skip this tutorial if you don’t want to run in parallel. This tutorial does not use the GUI.

To partition:
Copy folder <tutorial11\input> to <tutorial11\workdir>.
Create a new file using a text editor, containing the following single line (Windows):
call "<installDir>\x64\bin\run_dflowfm.bat"
"--partition:ndomains=3:icgsolver=6" westernscheldt11.mdu
or (Linux):
<installDir>/lnx64/bin/run_dflowfm.sh
--partition:ndomains=3:icgsolver=6 westernscheldt11.mdu
where <installDir> refers to your Delft3D installation directory.
Save the file in folder <tutorial11\workdir\dflowfm>
Windows:
Extension .bat is common, e.g. <run_partitioner.bat>. Double-quotes are necessary
around the executable name (if the path contains white spaces) and each argument (if it
contains the equal sign).
Linux:
Extension .sh is common, e.g. <run_partitioner.sh>. It’s a good habit to start the
file with an interpreter reference, e.g. #!/bin/bash. Be sure that the line endings of
your script file are conform Linux ("line feed" only). You can use the Linux command
dos2unix <scriptfile> to convert it.
Execute your run_partitioner script.

Deltares 355 of 562

 Tutorial

Remarks:
⋄ Example models, with run scripts, are included in the (open source) code. After regis-
tering yourself at https://oss.deltares.nl/, you can have a look at:
https://svn.oss.deltares.nl/repos/delft3d/trunk/examples
/12_dflowfm/test_data/e02_f14_c040_westerscheldt
⋄ The following text block is a subset of the text echoed to the command box via stdout
(version numbers and dates may differ). The full stdout text is saved in file
<tutorial11\output\dflowfm\run_partitioner_stdout.log>:

T
call "c:\Deltares\x64\bin\run_dflowfm.bat" "--partition:ndomains=3:icgsolver=6" westernscheldt11.mdu
OMP_NUM_THREADS is 2
Working directory: c:\checkouts\ds\doc\user_manuals_tutorial_data\Tutorial_D-Flow_FM\tutorial11\workdir\dflowfm
D3D_HOME : c:\Deltares\x64\bin\..
ARCH : x64
executing: "c:\Deltares\x64\dflowfm\bin\dflowfm-cli.exe" --nodisplay --autostartstop "--partition:ndomains=3:icgsolver=6" westernscheldt11.mdu
* Deltares, D-Flow FM Version 1.2.94.66020M, Feb 20 2020, 09:26:11
** WARNING: readMDUFile: [numerics] jaorgsethu=1 was in file, but not used. Check possible typo.
** WARNING: readMDUFile: [physics] effectspiral=0 was in file, but not used. Check possible typo.

**
AF
** WARNING: readMDUFile: [output] wrishp_enc=0 was in file, but not used. Check possible typo.
** INFO : Network UGRID-File: No 1D-Mesh Present, Skipped 1D
ug_get_meshgeom, #12, ierr=0
WARNING: Could not read net cells from netCDF file 'westernscheldt04_net.nc' (is not critical). Details follow:

gk_mcore statistics
coresize: 100432 nmops: 2048 cmop: 0
num_callocs: 249 num_hallocs: 0
size_callocs: 831160 size_hallocs: 0
cur_callocs: 0 cur_hallocs: 0
max_callocs: 100280 max_hallocs: 0
nbrpool statistics
nbrpoolsize: 0 nbrpoolcpos: 0
nbrpoolreallocs: 0

** INFO : added node-based ghostcells: 25

** WARNING: 1 hanging 2D links disregarded.
** INFO : added node-based ghostcells: 18
** INFO : added node-based ghostcells: 43
DR

Folder <tutorial11\output\dflowfm> contains the resulting run_partitioner scripts (contain-

ing paths that fit to the installation directories used at Deltares), Windows and Linux, and the
output for this tutorial exercise:
⋄ Three additional mdu-files:
<westernscheldt11_0000.mdu>
<westernscheldt11_0001.mdu>
<westernscheldt11_0002.mdu>
⋄ Three additional net.nc-files:
<westernscheldt04_0000_net.nc>
<westernscheldt04_0001_net.nc>
<westernscheldt04_0002_net.nc>
⋄ File <DFM_interpreted_idomain_westernscheldt04_net.nc> containing partition domain
information and cell information
⋄ Diagnosis file <DFM_OUTPUT_westernscheldt11\westernscheldt11.dia>
⋄ File <tutorial11\output\dflowfm\run_partitioner_stdout.log> containing the full text echoed
to the command box via stdout (version numbers and dates may differ).

Deltares 356 of 562

 Tutorial

23.1.13 Tutorial 12: Running a model using a batch script

This tutorial explains how to run D-Flow FM computations outside the GUI, using a batch
script. The resulting files of section 23.1.12 are used as input. At first, the model is run
sequentially (without parallelMPI), both on Windows and Linux. Next, the model is run with
parallelMPI (Windows and Linux). See section 8.3 for more information.

Remark:
⋄ Performing a computation in parallel is intended to speed-up the computation. But when
using limited resources for a small testcase (e.g. this tutorial), a parallel computation

T
might need more time. See also section 8.5.

Preparation:
Copy folder <tutorial12\input> to <tutorial12\workdir>.
AF Folder <tutorial12\output> contains the resulting files of all four runs:
⋄ Sequential on Windows
<dimr_config.xml>, as copied from the input folder
⋄ ⋄ ⋄

<run_model.bat>, as created in section 23.1.13.1

<run_model_bat_stdout.log>, containing the messages written to the command box
via stdout during the simulation
<dflowfm\DFM_OUTPUT_westernscheldt12_sequential> containing all the output files.
⋄

⋄ Sequential on Linux
<dimr_config.xml>, as copied from the input folder
DR ⋄ ⋄ ⋄

<run_model.sh>, as created in section 23.1.13.2

<run_model_sh_stdout.log>, containing the messages written to the command box
via stdout during the simulation
<dflowfm\DFM_OUTPUT_westernscheldt12_sequential> containing all the output files
⋄

(produced on Windows).
⋄ Parallel on Windows
<dimr_config_parallel.xml>, as created in section 23.1.13.3
⋄ ⋄ ⋄

<run_model_parallel.bat>, as created in section 23.1.13.3

<run_model_parallel_bat_stdout.log>, containing the messages written to the com-
mand box via stdout during the simulation
<dflowfm\DFM_OUTPUT_westernscheldt12_parallel> containing all the output files.
⋄

⋄ Parallel on Linux
<dimr_config_parallel.xml>, as created in section 23.1.13.4
⋄ ⋄ ⋄

<run_model_parallel.sh>, as created in section 23.1.13.4

<run_model_parallel_sh_stdout.log>, containing the messages written to the com-
mand box via stdout during the simulation
<dflowfm\DFM_OUTPUT_westernscheldt12_parallel> containing all the output files
⋄

(produced on Windows).

Deltares 357 of 562

 Tutorial

23.1.13.1 Sequential on Windows

Create a new file using a text editor, containing the following single line:
call "<installDir>\x64\bin\run_dimr.bat" dimr_config.xml
where <installDir> refers to your Delft3D installation directory.
Save the file in folder <tutorial12\workdir>
Extension .bat is common, e.g. <run_model.bat>. Double-quotes are necessary around
the executable name (if the path contains white spaces).
Execute your run_model script.

The following text block is a subset of the text echoed to the command box via stdout (version

T
numbers and dates may differ). The full stdout text is saved in file <tutorial12\output\run_model_bat_stdout.log>:

call "c:\Deltares\x64\bin\run_dimr.bat" dimr_config.xml

Configfile:dimr_config.xml
OMP_NUM_THREADS is 2
AF
Working directory: c:\Tutorial_D-Flow_FM\tutorial12\workdir
executing: "c:\Deltares\x64\bin\..\bin\dimr.exe" dimr_config.xml
Dimr [2020-04-28 17:46:14.198] #0 >> Deltares, DIMR_EXE Version 2.00.00.66020M, Feb 20 2020, 09:06:14
Dimr [2020-04-28 17:46:14.225] #0 >>
Dimr [2020-04-28 17:46:14.225] #0 >> Version Information of Components
Dimr [2020-04-28 17:46:14.227] #0 >> =================================
Dimr [2020-04-28 17:46:14.228] #0 >> dflowfm : 1.2.94.66020M
Dimr [2020-04-28 17:46:14.229] #0 >> ---------------------------------
Dimr [2020-04-28 17:46:14.229] #0 >>
Dimr [2020-04-28 17:46:14.233] #0 >> westernscheldt10.Initialize(westernscheldt12.mdu)
** DEBUG : 0 0.1000010 NOD(KMAX)
** DEBUG : 6 0.7000070 XK (KMAX), YK (KMAX), ZK (KMAX), KC (KMAX), NMK (KMAX), RNOD(KMAX)
loading model
Dimr [2020-04-28 17:46:14.370] #0 >> kernel: readMDUFile: [numerics] jaorgsethu=1 was in file, but not used. Check possible typo.
Dimr [2020-04-28 17:46:14.372] #0 >> kernel: readMDUFile: [physics] effectspiral=0 was in file, but not used. Check possible typo.
Dimr [2020-04-28 17:46:14.373] #0 >> kernel: readMDUFile: [output] wrishp_enc=0 was in file, but not used. Check possible typo.
ug_get_meshgeom, #12, ierr=0
** INFO : Opened file : westernscheldt05.ldb
** INFO : Closed file : westernscheldt05.ldb
** INFO : Opened file : westernscheldt06_obs.xyn
** INFO : Closed file : westernscheldt06_obs.xyn
DR

** INFO : Opened file : westernscheldt06crs_crs.pli

** INFO : Closed file : westernscheldt06crs_crs.pli
model loaded
Initializing flow: flow_modelinit
** INFO : Initializing flow model geometry...
** INFO : Done writing initial output to file(s).
Dimr [2020-04-28 17:46:14.913] #0 >> westernscheldt10.Update(43200.0)
Dimr [2020-04-28 17:46:23.950] #0 >> westernscheldt10.Finalize()
** INFO :
** INFO : Computation started at: 17:46:14, 28-04-2020
** INFO : Computation finished at: 17:46:24, 28-04-2020
** INFO :
** INFO : simulation period (h) : 12.0000000000
** INFO : total time in timeloop (h) : 0.0025600000
** INFO : MPI : no.
** INFO : OpenMP : yes. #threads max : 2
** INFO :
** INFO :
** INFO :
** INFO : Opened file : DFM_OUTPUT_westernscheldt12\westernscheldt12_numlimdt.xyz
** INFO : Closed file : DFM_OUTPUT_westernscheldt12\westernscheldt12_numlimdt.xyz
** INFO :
Dimr [2020-04-28 17:46:24.048] #0 >> TIMER INFO:

Dimr [2020-04-28 17:46:24.048] #0 >> westernscheldt10 : 9.999813 sec

23.1.13.2 Sequential on Linux

Create a new file using a text editor, containing the following single line:
<installDir>/lnx64/bin/run_dimr.sh dimr_config.xml
where <installDir> refers to your Delft3D installation directory.
Save the file in folder <tutorial12\workdir>
Extension .sh is common, e.g. <run_model.sh>. It’s a good habit to start the file with an
interpreter reference, e.g. #!/bin/bash. Be sure that the line endings of your script file are
conform Linux ("line feed" only). You can use the Linux command dos2unix <scriptfile>
to convert it.
Execute your run_model script.

The following text block is a subset of the text echoed to the command box via stdout (version
numbers and dates may differ). The full stdout text is saved in file

Deltares 358 of 562

 Tutorial

<tutorial12\output\run_model_sh_stdout.log>:

OMP_NUM_THREADS is 2
Configfile : dimr_config.xml
D3D_HOME : /opt/delft3d/lnx64
Working directory: /p/tutorial12/workdir
Number of slots : 1

executing:
/opt/delft3d/lnx64/bin/dimr dimr_config.xml
Dimr [2020-04-28 17:53:43.80130] #0 >> Deltares, DIMR_EXE Version 2.00.00.66020, Feb 19 2020, 18:57:44
Dimr [2020-04-28 17:53:43.161476] #0 >>
Dimr [2020-04-28 17:53:43.161494] #0 >> Version Information of Components
Dimr [2020-04-28 17:53:43.161497] #0 >> =================================
Dimr [2020-04-28 17:53:43.165592] #0 >> dflowfm : 1.2.94.66020

T
Dimr [2020-04-28 17:53:43.165605] #0 >> ---------------------------------
Dimr [2020-04-28 17:53:43.165609] #0 >>
Dimr [2020-04-28 17:53:43.165633] #0 >> westernscheldt10.Initialize(westernscheldt12.mdu)
** DEBUG : 0 0.1000010 NOD(KMAX)
** DEBUG : 6 0.7000070 XK (KMAX), YK (KMAX), ZK (KMAX), KC (KMAX), NMK (KMAX), RNOD(KMAX)
loading model
Dimr [2020-04-28 17:53:43.212208] #0 >> kernel: readMDUFile: [numerics] jaorgsethu=1 was in file, but not used. Check possible typo.
Dimr [2020-04-28 17:53:43.212220] #0 >> kernel: readMDUFile: [physics] effectspiral=0 was in file, but not used. Check possible typo.
Dimr [2020-04-28 17:53:43.212233] #0 >> kernel: readMDUFile: [output] wrishp_enc=0 was in file, but not used. Check possible typo.
** INFO : Done writing initial output to file(s).
Dimr [2020-04-28 17:53:43.846829] #0 >> westernscheldt10.Update(43200.0)
AF
Dimr [2020-04-28 17:53:55.290457] #0 >> westernscheldt10.Finalize()
** INFO
** INFO
** INFO
:
: Computation started at: 17:53:43, 28-04-2020
: Computation finished at: 17:53:55, 28-04-2020
** INFO :
** INFO : simulation period (h) : 12.0000000000
** INFO : total time in timeloop (h) : 0.0032725000
** INFO : MPI : no.
** INFO : OpenMP : unavailable.
** INFO :
** INFO :
** INFO :
** INFO : Opened file : DFM_OUTPUT_westernscheldt12/westernscheldt12_numlimdt.xyz
** INFO : Closed file : DFM_OUTPUT_westernscheldt12/westernscheldt12_numlimdt.xyz
** INFO :
Dimr [2020-04-28 17:53:55.313464] #0 >> TIMER INFO:

Dimr [2020-04-28 17:53:55.313478] #0 >> westernscheldt10 : 12.147715 sec

DR

23.1.13.3 Parallel on Windows

Check that hydra_service is running as a service on your machine, see section 8.4.3.
Check that your model is partitioned correctly, see section 23.1.12. In this example the
model is partitioned in three parts.
Open file <dimr_config.xml> in a text editor, add the following two lines to the <compo-
nent>-group:
<mpiCommunicator>DFM_COMM_DFMWORLD</mpiCommunicator>
<process>0 1 2</process>
where the process numbers must match exactly with the number of partitions. Save the
file as <dimr_config_parallel.xml>.
This step is identical for Linux and Windows.
Create a new file using a text editor, containing the following single line:
call "<installDir>\x64\bin\run_dimr_parallel.bat" 3 dimr_config_parallel.xml
where <installDir> refers to your Delft3D installation directory.
Save the file in folder <tutorial12\workdir>
Extension .bat is common, e.g. <run_model_parallel.bat>. Double-quotes are neces-
sary around the executable name (if the path contains white spaces).
Execute your run_model_parallel script.

The following text block is a subset of the text echoed to the command box via stdout (version
numbers and dates may differ). The full stdout text is saved in file
<tutorial12\output\run_model_parallel_bat_stdout.log>.
The "Access is denied" error messages are generated by the operating system and can be
neglected:

c:\Deltares\x64\bin\run_dimr_parallel.bat" 3 dimr_config_parallel.xml
Configfile:dimr_config_parallel.xml

Deltares 359 of 562

 Tutorial

OMP_NUM_THREADS is 2
number of partitions: 3
Working directory: c:\tutorial12\workdir
executing: "c:\Deltares\x64\share\bin\mpiexec.exe" -n 3 -localonly "c:\Deltares\x64\dimr\bin\dimr.exe" dimr_config_parallel.xml
#1: Running parallel with 3 partitions
#0: Running parallel with 3 partitions
#2: Running parallel with 3 partitions
Dimr [2020-04-28 17:48:31.383] #1 >> Deltares, DIMR_EXE Version 2.00.00.66020M, Feb 20 2020, 09:06:14
Dimr [2020-04-28 17:48:31.383] #2 >> Deltares, DIMR_EXE Version 2.00.00.66020M, Feb 20 2020, 09:06:14
Dimr [2020-04-28 17:48:31.383] #0 >> Deltares, DIMR_EXE Version 2.00.00.66020M, Feb 20 2020, 09:06:14
Dimr [2020-04-28 17:48:31.428] #0 >>
Dimr [2020-04-28 17:48:31.428] #0 >> Version Information of Components
Dimr [2020-04-28 17:48:31.428] #0 >> =================================
Dimr [2020-04-28 17:48:31.428] #0 >> dflowfm : 1.2.94.66020M
Dimr [2020-04-28 17:48:31.428] #0 >> ---------------------------------
Dimr [2020-04-28 17:48:31.428] #0 >>
Dimr [2020-04-28 17:48:31.429] #2 >> westernscheldt10.Initialize(westernscheldt12.mdu)
Dimr [2020-04-28 17:48:31.429] #1 >> westernscheldt10.Initialize(westernscheldt12.mdu)

T
Dimr [2020-04-28 17:48:31.429] #0 >> westernscheldt10.Initialize(westernscheldt12.mdu)
** DEBUG : 0 0.1000010 NOD(KMAX)
** DEBUG : 6 0.7000070 XK (KMAX), YK (KMAX), ZK (KMAX), KC (KMAX), NMK (KMAX), RNOD(KMAX)
** DEBUG : 0 0.1000010 NOD(KMAX)
** DEBUG : 6 0.7000070 XK (KMAX), YK (KMAX), ZK (KMAX), KC (KMAX), NMK (KMAX), RNOD(KMAX)
** DEBUG : 0 0.1000010 NOD(KMAX)
** DEBUG : 6 0.7000070 XK (KMAX), YK (KMAX), ZK (KMAX), KC (KMAX), NMK (KMAX), RNOD(KMAX)
loading model
loading model
loading model
AF
** INFO
** INFO
** INFO
: no partitioning polygons file: read subdomain numbering from netfiles
: no partitioning polygons file: read subdomain numbering from netfiles
: no partitioning polygons file: read subdomain numbering from netfiles
Dimr [2020-04-28 17:48:31.585] #1 >> kernel: readMDUFile: [numerics] jaorgsethu=1 was in file, but not used. Check possible typo.
Dimr [2020-04-28 17:48:31.585] #0 >> kernel: readMDUFile: [numerics] jaorgsethu=1 was in file, but not used. Check possible typo.
Dimr [2020-04-28 17:48:31.586] #2 >> kernel: readMDUFile: [numerics] jaorgsethu=1 was in file, but not used. Check possible typo.
model loaded
model loaded
model loaded
Initializing flow: flow_modelinit
Initializing flow: flow_modelinit
Initializing flow: flow_modelinit
** INFO : Initializing flow model geometry...
** INFO : Initializing flow model geometry...
** INFO : Initializing flow model geometry...
** INFO : Modelinit finished at: 17:48:31, 28-04-2020
** INFO : Modelinit finished at: 17:48:31, 28-04-2020
** INFO : Modelinit finished at: 17:48:31, 28-04-2020
Dimr [2020-04-28 17:48:31.918] #1 >> westernscheldt10.Update(43200.0)
Dimr [2020-04-28 17:48:31.927] #2 >> westernscheldt10.Update(43200.0)
Dimr [2020-04-28 17:48:31.943] #0 >> westernscheldt10.Update(43200.0)
DR

** INFO : Solver converged in 1 iterations, res= 0.2520E-14 dt = 1.0909

** INFO : Solver converged in 1 iterations, res= 0.1215E-13 dt = 1.1891
** INFO : Solver converged in 1 iterations, res= 0.4507E-13 dt = 1.2936
** INFO : Solver converged in 1 iterations, res= 0.1650E-12 dt = 1.4198
** INFO : Solver converged in 2 iterations, res= 0.1549E-19 dt = 1.5541
** INFO : Solver converged in 2 iterations, res= 0.2529E-19 dt = 1.6933
** INFO : Solver converged in 22 iterations, res= 0.6721E-12 dt = 30.0000
** INFO : Solver converged in 22 iterations, res= 0.6637E-12 dt = 30.0000
** INFO : Solver converged in 22 iterations, res= 0.6550E-12 dt = 30.0000
** INFO : Solver converged in 22 iterations, res= 0.6461E-12 dt = 30.0000
Dimr [2020-04-28 17:48:39.823] #0 >> westernscheldt10.Finalize()
Dimr [2020-04-28 17:48:39.823] #2 >> westernscheldt10.Finalize()
Dimr [2020-04-28 17:48:39.825] #1 >> westernscheldt10.Finalize()
Dimr [2020-04-28 17:48:39.829] #0 >> TIMER INFO:

Dimr [2020-04-28 17:48:39.829] #0 >> westernscheldt10 : 8.400 sec

Dimr [2020-04-28 17:48:39.830] #2 >> TIMER INFO:

Dimr [2020-04-28 17:48:39.830] #2 >> westernscheldt10 : 8.400 sec

Dimr [2020-04-28 17:48:39.831] #1 >> TIMER INFO:

Dimr [2020-04-28 17:48:39.831] #1 >> westernscheldt10 : 8.402 sec

23.1.13.4 Parallel on Linux

Check that the Intel MPI library is installed on your system. If not, then open the D-Flow FM
Installation Manual how to install the Intel MPI library either on Windows or on CentOS.
Check that your model is partitioned correctly, see section 23.1.12. In this example the
model is partitioned in three parts.
Open file <dimr_config.xml> in a text editor, add the following two lines to the <compo-
nent>-group:
<mpiCommunicator>DFM_COMM_DFMWORLD</mpiCommunicator>
<process>0 1 2</process>
where the process numbers must match exactly with the number of partitions. Save the
file as <dimr_config_parallel.xml>.
This step is identical for Linux and Windows.
Create a new file using a text editor, containing the following single line:
<installDir>/lnx64/bin/run_dimr.sh -c 3 -m dimr_config_parallel.xml

Deltares 360 of 562

 Tutorial

where <installDir> refers to your Delft3D installation directory.

Save the file in folder <tutorial12\workdir>
Extension .sh is common, e.g. <run_model_parallel.sh>. It’s a good habit to start the
file with an interpreter reference, e.g. #!/bin/bash. Be sure that the line endings of
your script file are conform Linux ("line feed" only). You can use the Linux command
dos2unix <scriptfile> to convert it.
Execute your run_model_parallel script.

The following text block is a subset of the text echoed to the command box via stdout (version
numbers and dates may differ). The full stdout text is saved in file

T
<tutorial12\output\run_model_parallel_sh_stdout.log>:

OMP_NUM_THREADS is 2
Configfile : dimr_config_parallel.xml
D3D_HOME : /opt/delft3/lnx64
AF
Working directory:
Number of slots :
/p/tutorial12/workdir
3

Contents of machinefile:

----------------------------------------------------------------------
executing:
mpiexec -np 3 /opt/delft3d/lnx64/bin/dimr dimr_config_parallel.xml
#2: Running parallel with 3 partitions
Dimr [2020-04-28 17:56:13.428935] #2 >> Deltares, DIMR_EXE Version 2.00.00.66020, Feb 19 2020, 18:57:44
#0: Running parallel with 3 partitions
Dimr [2020-04-28 17:56:13.429264] #0 >> Deltares, DIMR_EXE Version 2.00.00.66020, Feb 19 2020, 18:57:44
#1: Running parallel with 3 partitions
Dimr [2020-04-28 17:56:13.429398] #1 >> Deltares, DIMR_EXE Version 2.00.00.66020, Feb 19 2020, 18:57:44
Dimr [2020-04-28 17:56:13.457510] #2 >> westernscheldt10.Initialize(westernscheldt12.mdu)
Dimr [2020-04-28 17:56:13.457522] #1 >> westernscheldt10.Initialize(westernscheldt12.mdu)
Dimr [2020-04-28 17:56:13.457722] #0 >>
Dimr [2020-04-28 17:56:13.457742] #0 >> Version Information of Components
Dimr [2020-04-28 17:56:13.457746] #0 >> =================================
Dimr [2020-04-28 17:56:13.457802] #0 >> dflowfm : 1.2.94.66020
Dimr [2020-04-28 17:56:13.457807] #0 >> ---------------------------------
DR

Dimr [2020-04-28 17:56:13.457810] #0 >>

Dimr [2020-04-28 17:56:13.457827] #0 >> westernscheldt10.Initialize(westernscheldt12.mdu)
** DEBUG : 0 0.1000010 NOD(KMAX)
** DEBUG : 6 0.7000070 XK (KMAX), YK (KMAX), ZK (KMAX), KC (KMAX), NMK (KMAX), RNOD(KMAX)
** DEBUG : 0 0.1000010 NOD(KMAX)
** DEBUG : 6 0.7000070 XK (KMAX), YK (KMAX), ZK (KMAX), KC (KMAX), NMK (KMAX), RNOD(KMAX)
** DEBUG : 0 0.1000010 NOD(KMAX)
** DEBUG : 6 0.7000070 XK (KMAX), YK (KMAX), ZK (KMAX), KC (KMAX), NMK (KMAX), RNOD(KMAX)
loading model
loading model
loading model
Dimr [2020-04-28 17:56:13.498662] #0 >> kernel: readMDUFile: [numerics] jaorgsethu=1 was in file, but not used. Check possible typo.
Dimr [2020-04-28 17:56:13.499212] #2 >> kernel: readMDUFile: [numerics] jaorgsethu=1 was in file, but not used. Check possible typo.
Dimr [2020-04-28 17:56:13.501699] #1 >> kernel: readMDUFile: [numerics] jaorgsethu=1 was in file, but not used. Check possible typo.
model loaded
model loaded
model loaded
Initializing flow: flow_modelinit
Initializing flow: flow_modelinit
Initializing flow: flow_modelinit
** INFO : Initializing flow model geometry...
** INFO : Initializing flow model geometry...
** INFO : Initializing flow model geometry...
Dimr [2020-04-28 17:56:14.3507] #2 >> westernscheldt10.Update(43200.0)
Dimr [2020-04-28 17:56:14.28873] #1 >> westernscheldt10.Update(43200.0)
Dimr [2020-04-28 17:56:14.218837] #0 >> westernscheldt10.Update(43200.0)
** INFO : Solver converged in 1 iterations, res= 0.2520E-14 dt = 1.0909
** INFO : Solver converged in 1 iterations, res= 0.1215E-13 dt = 1.1891
** INFO : Solver converged in 1 iterations, res= 0.4507E-13 dt = 1.2936
** INFO : Solver converged in 1 iterations, res= 0.1650E-12 dt = 1.4198
** INFO : Solver converged in 2 iterations, res= 0.1562E-19 dt = 1.5541
** INFO : Solver converged in 2 iterations, res= 0.2280E-19 dt = 1.6933
** INFO : Solver converged in 22 iterations, res= 0.6871E-12 dt = 30.0000
** INFO : Solver converged in 22 iterations, res= 0.6800E-12 dt = 30.0000
** INFO : Solver converged in 22 iterations, res= 0.6721E-12 dt = 30.0000
** INFO : Solver converged in 22 iterations, res= 0.6637E-12 dt = 30.0000
** INFO : Solver converged in 22 iterations, res= 0.6550E-12 dt = 30.0000
** INFO : Solver converged in 22 iterations, res= 0.6461E-12 dt = 30.0000
Dimr [2020-04-28 17:56:21.41192] #2 >> westernscheldt10.Finalize()
Dimr [2020-04-28 17:56:21.42046] #1 >> westernscheldt10.Finalize()
Dimr [2020-04-28 17:56:21.48210] #0 >> westernscheldt10.Finalize()
Dimr [2020-04-28 17:56:21.51045] #1 >> TIMER INFO:

Dimr [2020-04-28 17:56:21.51055] #1 >> westernscheldt10 : 7.593429 sec

Dimr [2020-04-28 17:56:21.51064] #2 >> TIMER INFO:

Dimr [2020-04-28 17:56:21.51078] #2 >> westernscheldt10 : 7.593434 sec

Dimr [2020-04-28 17:56:21.53908] #0 >> TIMER INFO:

Dimr [2020-04-28 17:56:21.53917] #0 >> westernscheldt10 : 7.595980 sec

Deltares 361 of 562

 Tutorial

23.2 Tutorial Hydrodynamics for 3D modelling

23.2.1 Outline of the tutorials for 3D modelling

In this one-hour tutorial you will experience the basic functionality for 3D modelling with D-
Flow FM. This manual contains two tutorials on 3D modelling (with indication of the estimated
time):
⋄ Tutorial 13 (section 23.2.2): Set-up of a 3D model and running this model (30 minutes).
⋄ Tutorial 14 (section 23.2.3): Viewing the output of a 3D model simulation (30 minutes).

T
The necessary input files for these two tutorials can be found in the folders tutorial13 and
tutorial14. When saving your model data while working through these tutorials, be sure not
to overwrite the tutorial data. Ideally, you should create a seperate working folder somewhere
else on your computer to save your work. The folder finished in each tutorial folder contains
AF the output generated by Deltares as a reference.

It is strongly recommend to at first read Chapter 10 on 3D modelling. In this chapter the

keywords for 3D modelling are explained, which is not the case in the two 3D tutorial exercises
below.

23.2.2 Tutorial 13: Set-up of a 3D model, running this model and postprocessing
In this tutorial exercise a simplified deep water 3D model will be set-up. Also a simulation
will be carried out and the model results will be visualized for this 3D model. We start with
a simplified 2D model for a shelf break and will step by step extend this model towards a 3D
DR

model with z-σ -co-ordinates in the vertical.

Import the D-Flow FM model from the folder <tutorial13>, by choosing Import → Flow
Flexible Mesh Model → OK. Choose <shelf_break_2D.mdu> and press Open.
In the Map window select <Bed Level>. Switch on the legend by selecting via Legend in
the main menu bar. Next, select contour classes as shown in Figure 23.34 by right mouse
clicking on Bed Level in the Map window, selecting Legend Properties and choosing 11
classes in the range of 500 to -4500. Also switch on the <Open Street Map>. Then, your
window should look like in Figure 23.34.

Deltares 362 of 562

 Tutorial

T
AF
Figure 23.34: Model domain with a shelf break.

It can be seen that the bed levels varies from 0 m to a few hundred meters in the coastal zone.
Then, after the shelf break the bed level rapidly increases to a depth of about 4300 m.
DR

DoubleClick on General in the Project window. Apart form the General settings
other tabs will appear.
Choose the tab 3D Layers and specify the following:
Kmx = 25, the number of vertical layers;
Layer type = 2, indicating that the layer type is based on z-layers;
DzTop = 2.5, being the z-layer thickness of layers above level Dztopuniabovez;
FloorLevTopLay = - 2.5, indicating the floor level of top layer;
DzTopUniAboveZ = -40.0, indicating that above level Dztopuniabovez layers
will have uniform a thickness of Dztop, while the sigmaGrowthFactor is applied be-
low this level;
NumTopSig = 16, representing the number of sigma-layers on top of the z-layers;
NumTopSigUniform = 0, indicating whether the number of sigma-layers in a z-sigma-
model is constant (=1) or decreasing (=0) (depending on local depth);
SigmaGrowthFactor = 1.18, representing the increase in layer thickness below
the level specified for Dztopuniabovez.

Deltares 363 of 562

 Tutorial

T
Figure 23.35: Specification of Z-sigma layers

Finally: Rename the Flow FM model in the Project window to shelf_break_3D;

AF
and
Export the model to (DIMR Configuration) files.

Next, we will carry out a simulation with this 3D model. This can be done via a simulation
inside the GUI or outside the GUI. We prefer to do the simulation outside the GUI, because
this will go slightly faster. Moreover, then simulations can be done in parallel mode on multiple
cores. The latter is not possible via the GUI.

Open file <run_dimr.bat> and check whether the path specified in this file for the D-
Flow FM executable is valid on your computer.
If the path is not valid, because for example another Delft3D Flexible Mesh release has
DR

been installed on your computer, then change this path so that it refer to a D-Flow FM
executable on your computer. Noted that there is no progress available. If the keyword
StatInterval has been activated, then the progress can be checked in the diagnostic
file of the simulation.
Double click on <run_dimr.bat> so that the simulation will start. The simulation will
roughly take five minutes, depending on the computing power of your computer.
When the simulation has finished, go to folder <output> in folder <tutorial13> and open
file <shelf_break_3D.dia>. Check whether the simulation has come to a normal end,
which can be checked at the end of this file. For example, the average time step should
be in the order of 45 s.

Now we will visualize the results of this 3D model.

To that purpose start the Delft3D-QUICKPLOT program by double clicking on its icon on
your desktop.
Select the MAP output via File → Open File and then go the folder <output> and select
file <shelf_break_3D_map.nc>.
Click on the <Grid icon> as shown in Figure 23.36.

Figure 23.36: Icon for grid selection.

Deltares 364 of 562

 Tutorial

Click on the sixth icon and draw an arbitrary line as shown in Figure 23.37.

T
AF
DR

Figure 23.37: Location of 2DV cross section.

Select quantity Salinity in flow element –nmesh2d_face: mean.

For the Presentation Type click on patches with lines.
For the Colour select the white colour instead of the blue colour, which is the default.
Click on Quick View and the figure will show up as in Figure 23.38.

Deltares 365 of 562

 Tutorial

T
AF
DR

Figure 23.38: Overall 2DV cross section of salinity including layer interfaces.

Now zoom into the shelf break so that a figure will appear as in Figure 23.39.

Deltares 366 of 562

 Tutorial

T
AF
DR

Figure 23.39: 2DV cross section of salinity including layer interfaces at shelf break.

It can be seen that in the top 40 meters of the water column 16 layers of a thickness of
about 2.5 m appear, which represent the σ layers in this model. Now, we will zoom into
the deeper part of the model domain.
Therefore, at first zoom out again to the whole cross section and then zoom in to the deep
part as shown in Figure 23.40.

Deltares 367 of 562

 Tutorial

T
AF
DR

Figure 23.40: 2DV cross section of salinity including layer interfaces at deep part.

It can be seen that the layer thicknesses rapidly increase for the larger depths. All layer
interfaces are strictly horizontal except for the two deepest layers. In order to prevent very
thin layers near the bed, which is unwanted from a numerical point of view, the two deepest
layers have the same thickness. Consequently, the interfaces in the two bed layers aren’t
strictly horizontal.
In this model there are σ layers near the surface and z-layers in the deeper part. This
is a much preferred combination, because σ layers can lead to artificial mixing in areas
of steep bed topography, due to the hydrostatic inconsistency (Haney, 1991). On the
other hand, z layers can lead to stair cases near the surface. Moreover, a top layer can
become very thin, so that the ratio in layer thickness with the next layer can be large,
which is unwanted from a numerical point of view. This might lead to a small time step
and therefore huge computation time. By applying σ layers near the surface and z layers
in the deeper parts, the disadvantages of both approaches are largely circumvented.

In summary, in this tutorial exercise a simplified 3D model was set-up that consists of a rela-
tively shallow part with depths up to about 100 meter, a shelf break and a deep part of more
than four kilometers deep. D-Flow FM has been developed for coastal applications and there-
fore focusses on processes in this relatively shallow areas of roughly a few hundred meters
deep. For such applications D-Flow FM performs adequately. However, D-Flow FM is also
used in oceanic applications with areas of kilometers deep. For these oceanic applications
software systems like HYCOM, NEMO and ROMS have been developed. These software sys-
tems are based on different numerical schemes and different turbulence models compared to
D-Flow FM, so that model results of D-Flow FM can be different for deep water applications.

Deltares 368 of 562

 Tutorial

23.2.3 Tutorial 14: Extra options for postprocessing of 3D model simulations

In this tutorial extra postprocessing options will be described for 3D modelling. This will be
done for a flume model with a length of 130 m. At the left open boundary there is a tidal
boundary with either inflow or outflow of water. At the right open boundary there is a small
inflow discharge of water.

In Figure 23.41 this flume model is visualized in the GUI of D-Flow FM. A meandering grid
is applied consisting of quadrangles with locally a grid refinement. In this figure an arbitrary
line has been drawn (in red). This section will be used for postprocessing, as we did in the

T
previous tutorial.

AF
Figure 23.41: Location of 2DV cross section.

Start the Delft3D-QUICKPLOT program by double clicking on its icon on your desktop.
Select the MAP output via File → Open File and then go the folder <tutorial14_output>
and select file <tidalflume_map.nc>.
Click on the Grid icon as shown in Figure 23.36.
Click on the sixth icon and draw an arbitrary line as shown in Figure 23.42.
DR

Deltares 369 of 562

 Tutorial

T
AF
DR

Figure 23.42: Location of 2DV cross section.

Select quantity Salinity in flow element –nmesh2d_face: mean.

For the Presentation Type click on continuous shades.
Click on Show Times and select 01-Sep-1992 00:54:00.
Click on Quick View and a figure will show up as in Figure 23.43.

Deltares 370 of 562

 Tutorial

T
AF
DR

Figure 23.43: 2DV cross sectional view of salinity.

Next, we will make a 2DV(ertical) cross sectional plot for the vertical eddy viscosity.

Therefore, Select quantity turbulent vertical eddy viscosity –mesh2d_nEdges: mean.

For the Presentation Type click on continuous shades.
Click on Show Times and select 01-Sep-1992 00:54:00.
Click on Quick View and a figure will show up as in Figure 23.44. Neglect the white vertical
bars, which is due to the postprocessing when interpolating along the chosen grid line.

Deltares 371 of 562

 Tutorial

T
AF
DR

Figure 23.44: 2DV cross sectional view of vertical eddy viscosity.

In Figure 23.43 it can be seen that in the area between 25 m en 45 m from the inflow boundary
salinity stratification occurs. In other parts of the model domain no vertical stratification of
salinity occurs. When looking at the vertical profiles for the vertical eddy viscosity, it can be
seen that parabolic profiles occur in the vertical in the areas without any stratification. This
is in line with the theory for well-mixed areas. However, in the area of vertical stratification,
the vertical profiles for the vertical eddy viscosity are different, which is in line with the theory
as well. In the validation document of D-Flow FM an almost similar flume model is validated
on salinity measurements. In this validation document it is shown that D-Flow FM accurately
computes the salinity intrusion in this tidal flume.

The previous figures were based on the map output file. We will now switch to proprocessing
for the history output file.

Therefore, select the history output via File → Open File and then go the folder <tutorial14_output>
and select file <tidalflume_his.nc>.
Select quantity sea_water_salinity.
Select station at 24 m.
Select layer k=10.
Select all time steps.
Click on Quick View and a figure will show up with only the blue line as in Figure 23.45.
Select layer k=1.
For the Colour select the red colour instead of the blue colour.
Click on Add to Plot and a figure will show up as in Figure 23.45.

Deltares 372 of 562

 Tutorial

T
AF
DR

Figure 23.45: Time history of salinity near surface and near bed.

Finally, we will generate a ZT(ime)-plot in which for one observation point the salinity concen-
trations will be shown during the whole simulation.

To that purpose select station at 24 m.

Select all layers.
Select all time steps.
For the Axes Type select Time-Z
For the Presentation Type click on continuous shades.
Click on Quick View and a figure will show up with salinity concentrations at 24 m form the
inflow boundary for the whole simulation period.
Now, zoom in the period from 20 to 50 minutes after the start. Then a figure will show up
as in Figure 23.46.

Deltares 373 of 562

 Tutorial

T
AF
DR

Figure 23.46: ZT plot of salinity at 24 m from inflow boundary.

In summary, in this tutorial several extra postprocessing options have been explained for a
tidal flume model. In this model only 10 σ layers are used. Despite its relatively low number
of layers an accurate vertical salinity stratification was computed. The computation of salinity
stratification and temperature stratification in the vertical is one of the nice features of 3D
modelling with D-Flow FM.

Deltares 374 of 562

 References
Andrews, D. G. and M. E. McIntyre, 1978. “An exact theory of nonlinear waves on a
Lagrangian-mean flow.” Journal of Fluid Mechanics 89 (4): 609–646.

Baptist, M. J., 2005. Modelling floodplain biogeomorphology. Ph.D. thesis, Delft University of
Technology.

Barenblatt, G. I., M. Bertsch, R. Dal Passo, V. M. Prostokishen and M. Ughi, 1993. “A mathe-
matical model of turbulent heat and mass transfer in stably stratified shear flow.” Journal of
Fluid Mechanics 253: 341–358.

T
Baumert, H. and G. Radach, 1992. “Hysteresis of Turbulent Kinetic Energy in Non-rotational
Tidal Flows: A Model Study.” Journal of Geophysical Research 97 (C3): 3669–3677.

Beckers, J. M., H. Burchard, J. M. Campin, E. Deleersnijder and P. P. Mathieu, 1998. “Another

AF
reason why simple discretizations of rotated diffusion operators cause problems in ocean
models: comments on “isoneutral diffusion in a z co-ordinate ocean model”.” American
Meteorological Society 28: 1552–1559.

Bijker, E. W., 1967. Some considerations about scales for coastal models with moveable bed.
Tech. Rep. 50, WL | Delft Hydraulics, Delft, The Netherlands.

Bos, 1989. Discharge Measuring Structures. International Institute for Land Reclamation and
Improvement/ILRI, Wageningen, The Netherlands.

Burchard, H. and H. Baumert, 1995. “On the performance of a mixed-large model based on
the k-epsilon turbulence closure.” Journal of Geophysical Research 100 (C5): 8523–8540.
DR

Charnock, H., 1955. “Wind-stress on a water surface.” Q. J. Royal Meteorol. Soc. 81: 639–
640.

Christoffersen, J. B. and I. G. Jonsson, 1985. “Bed friction and dissipation in a combined

current and wave motion.” Ocean Engineering 12 (5): 387–423.

Colebrook, C., 1939. “Turbulent flow in pipes, with particular reference to the transition region
between the smooth and rough pipe laws.” Journal of the Institution of Civil Engineers
11 (4): 133–156.

Colebrook, C. and C. White, 1937. “Experiments with Fluid Friction in Roughened Pipes.”
Proceedings of the Royal Society of London, Series A, Mathematical and Physical Sciences
161 (906): 367–381.

Davies, A. G., R. L. Soulsby and H. L. King, 1988. “A numerical model of the combined wave
and current bottom boundary layer.” Journal of Geophysical Research 93 (C1): 491–508.

Davies, A. M. and H. Gerritsen, 1994. “An intercomparison of three-dimensional tidal hydro-

dynamic models of the Irish Sea.” Tellus 46A: 200–221.

De Goede, E., 2020. “Historical overview of 2D and 3D hydrodynamic modelling of shal-

low water flows in the Netherlands.” Journal of Ocean Dynamics 70(4): 521–539. DOI:
https://doi.org/10.1007/s10236-019-01336-5.

Deltares, 2025a. D-Flow Flexible Mesh Technical Reference Manual. Deltares, Delft.

Deltares, 2025b. D-Flow Flexible Mesh User Manual; Released for Delft3D FM Suite 1D2D.
Deltares, Delft.

Deltares, 2025c. D-Flow FM Hydro- and Morphodynamics User Manual; Released for Delft3D
FM Suite 2D3D. Deltares, Delft.

Deltares 375 of 562

 References

Deltares, 2025d. D-Morphology 1D/2D/3D User Manual. Deltares, Delft.

Deltares, 2025e. D-Real Time Control User Manual; Released for Delft3D FM and SOBEK.
Deltares, Delft, 1.4 ed.

Deltares, 2025f. D-Water Quality Description of Input file. Deltares, 2.00 ed.

Deltares, 2025g. D-Water Quality Processes Library Configuration Tool User Manual.
Deltares, 0.01 ed.

Deltares, 2025h. D-Water Quality Technical Reference Manual. Deltares, 5.01 ed.

T
Deltares, 2025i. D-Water Quality User Manual. Deltares, 5.06 ed.

Deltares, 2025j. D-Waves User Manual; Simulation of short-crested waves with SWAN.
Deltares, Delft, 1.2 ed.
AF
Deltares, 2025k. Delft3D-FLOW User Manual; Simulation of multi-dimensional hydrodynamic
flows and transport phenomena, including sediments. Deltares, Delft, 4.05 ed.

Deltares, 2025l. Delft3D-RGFGRID User Manual; Generation and manipulation of structured

and unstructured grids, suitable for Delft3D-FLOW, Delft3D-WAVE or D-Flow Flexible Mesh.
Deltares, Delft, 7.00 ed.

Deltares, 2025m. DIMR Technical Reference Manual. Deltares, Delft.

Dijkstra, Y. M., 2014. Turbulence modelling in environmental flows. Improving the accuracy
of the k -ε model by a mathematical transformation. Master’s thesis, Delft University of
Technology. Faculty of Civil Engineering and Geosciences, Department of Environmental
DR

Fluid Mechanics.

Dingemans, M. W., 1997. Water Wave Propagation over Uneven Bottoms, Vol. 1 and 2.
Advanced Series on Ocean Engineering, Vol. 13. World Scientific, London.

Dingemans, M. W., A. C. Radder and H. J. de Vriend, 1987. “Computation of the driving forces
of wave-induced currents.” Coastal Engineering 11: 539–563.

Eckart, C., 1958. “Properties of water, Part II. The equation of state of water and sea water at
low temperatures and pressures.” American Journal of Science 256: 225–240.

ECMWF, 2023. IFS DOCUMENTATION – Cy48r1, Operational implementation 27 June 2023,

PART IV: PHYSICAL PROCESSES. Tech. rep., ECMWF.

Fofonoff, N. P. and R. C. Millard Jr., 1983. Algorithms for the computation of fundamental
properties of seawater. UNESCO Technical Papers in Marine Sciences 44, UNESCO, Paris,
France.

Fredsøe, J., 1984. “Turbulent boundary layer in wave-current interaction.” Journal of Hydraulic
Engineering 110: 1103–1120.

Garratt, J. R., 1977. “Review of Drag Coefficients over Oceans and Continents.” Review
Articles in Monthly Weather Review 105 (7): 915–929.

Gill, A. E., 1982. Atmosphere-Ocean dynamics, vol. 30 of International Geophysics Series.

Academic Press.

Grant, W. D. and O. S. Madsen, 1979. “Combined wave and current interaction with a rough
bottom.” Journal of Geophysical Research 84 (C1): 1797–1808.

Groeneweg, J., 1999. Wave-current interactions in a generalized Lagrangian mean formula-

tion. Delft University of Technology, Delft, The Netherlands. Ph.D. thesis.

Deltares 376 of 562

 References

Groeneweg, J. and G. Klopman, 1998. “Changes of the mean velocity profiles in the combined
wave-current motion in a GLM formulation.” Journal of Fluid Mechanics 370: 271–296.

Haney, R. L., 1991. “On the pressure gradient force over steep topography in sigma co-
ordinate models.” Journal of Physical Oceanography 21: 610–619.

Hersbach, H., 2011. “Sea Surface Roughness and Drag Coefficient as Functions of Neutral
Wind Speed.” Journal of Physical Oceanography 41 (1): 247–251.

Hibler III, W. D., 1979. “A dynamic thermokdynamic sea ice model.” Journal of Physical
Oceanography 9 (4): 815–846.

T
Hirsch, C., 1990. Numerical computation of internal and external flows. John Wiley & Sons,
New York.

Huang, W. and M. Spaulding, 1996. “Modelling horizontal diffusion with sigma coordinate
system.” Journal of Hydraulic Engineering 122 (6): 349–352.
AF
Hunke, E. C. and J. K. Dukowicz, 1997. “An elastic-ciscous-plastic model for sea ice.” Journal
of Physical Oceanography 27 (9): 1849–1867.

Huynh-Thanh, S. and A. Temperville, 1991. “A numerical model of the rough turbulent bound-
ary layer in combined wave and current interaction.” In R. L. Soulsby and R. Bettes, eds.,
Sand transport in rivers, estuaries and the sea, pages 93–100. Balkema Rotterdam.

Hwang, P., 2005a. “Comparison of the ocean surface wind stress computed with different
parameterization functions of the drag coefficient.” J. Oceanogr. 61: 91–107.

Hwang, P., 2005b. “Drag coefficient, dynamic roughness and reference wind speed.” J.
DR

Oceanogr. 61: 399–413.

Kalkwijk, J. P. T. and R. Booij, 1986. “Adaptation of secondary flow in nearly horizontal flow.”
Journal of Hydraulic Research 24 (1): 19–37.

Karypis, G., 2013. METIS - A Software Package for Partitioning Unstructured Graph, Parti-
tioning Meshes, and Computing Fill-Reducing Orderings of Sparse Matrices, Version 5.1.0.
Tech. rep., Department of Computer Science and Engineering, University of Minnesota.

Klopstra, D., H. J. Barneveld and J. M. Van Noortwijk, 1996. Analytisch model hydraulis-
che ruwheid van overstroomde moerasvegetatie. Tech. Rep. PR051, HKV consultants,
Lelystad, The Netherlands. Commissioned by Rijkswaterstaat/RIZA, The Netherlands.

Klopstra, D., H. J. Barneveld, J. M. Van Noortwijk and E. H. van Velzen, 1997. “Analytical
model for hydraulic roughness of submerged vegetation.” In The 27th IAHR Congress, San
Francisco, 1997; Proceedings of Theme A, Managing Water: Coping with Scarcity and
Abundance, pages 775–780. American Society of Civil Engineers (ASCE), New York.

Knaap, F. Van der, 2000. Breach growth as a function of time. Tech. Rep. Q2655, WL |
Delft Hydraulics, Delft, The Netherlands. Memos 2 and 3 of May 21 and September 5
respectively.

Kolmogorov, A. N., 1942. “Equations of turbulent motion in incompressible fluid.” Izv. Akad.
Nauk. SSR, Seria fizicheska Vi No.1 2 (1-2): 56–58. English translation: 1968 Imperial
College, Mech. Eng. Dept. Rept. ON/6.

Lane, A., 1989. The heat balance of the North Sea. Tech. Rep. 8, Proudman Oceanographic
Laboratory.

Leendertse, J. J., 1990. “Turbulence modelling of surface water flow and transport: part IVa.”
Journal of Hydraulic Engineering 114 (4): 603–606.

Deltares 377 of 562

 References

Love, A. E. H., 1927. A Treatise on the Mathematical Theory of Elasticity. Cambridge Univer-
sity Press, 4th ed.

Madec, G., M. Bell, R. Bourdallé-Badie, J. Chanut, E. Clementi, A. Coward, M. Drudi, I. Epic-

oco, C. Ethé, D. Iovino, D. Lea, C. Lévy, N. Martin, S. Masson, P. Mathiot, F. Mele, S. Mo-
cavero, A. Moulin, S. Müller, G. Nurser, G. Samson and D. Storkey, 2022. NEMO ocean
engine. Scientific Notes. Institut Pierre-Simon Laplace, Paris, France, v4.2 ed.

Manning, R., 1891. “On the flow of water in open channels and pipes.” Transactions of the
Institution of Civil Engineers of Ireland 20: 161–207.

T
Mellor, G. and A. F. Blumberg, 1985. “Modelling vertical and horizontal diffusivities with the
sigma coordinate system.” Monthly Weather Review 11: 1379–1383.

Mellor, G. L. and L. Kantha, 1989. “An ice-ocean coupled model.” Journal of Geophysical
Research 94 (8): 10937–10954.
AF
Millero, F. J. and A. Poisson, 1981. “International one-atmosphere equation of state of sea
water.” Deep-Sea Research 28A (6): 625–629.

Myrhaug, D. and O. H. Slaattelid, 1990. “A rational approach to wave-current friction coeffi-

cients for rough, smooth and transitional turbulent flow.” Coastal Engineering 14: 265–293.

O’ Connor, B. A. and D. Yoo, 1988. “Mean bed friction of combined wave-current flow.” Coastal
Engineering 12: 1–21.

Octavio, K. A. H., G. H. Jirka and D. R. F. Harleman, 1977. Vertical Heat Transport Mecha-
nisms in Lakes and Reservoirs. Tech. Rep. 22, Massachusetts Institute of Technology.
DR

Peckham, S. D., E. W. H. Hutton and B. Norris, 2013. “A component-based approach to

integrated modeling in the geosciences: The design of CSDMS.” Computers & Geosciences
53: 3–12.

Phillips, N. A., 1957. “A co-ordinate system having some special advantages for numerical
forecasting.” Journal of Meteorology 14: 184–185.

Platzek, F. W., G. S. Stelling, J. A. Jankowski and R. Patzwahl, 2012. “On the representation
of bottom shear stress in z-layer models.” In Hydroinformatics 2012. Hamburg, Germany.

Postma, L., G. S. Stelling and J. Boon, 1999. “Three-dimensional water quality and hydro-
dynamic modelling in Hong Kong. Stratification and water quality.” In Proceedings of the
2nd International Symp. on Environmental Hydraulics, Hong Kong, December 1998, pages
43–49. Balkema, Rotterdam.

Prandtl, L., 1945. “Über ein neues Formelsystem für die ausgebildete Turbulenz.” Nachrichten
von der Akademie der Wissenschaften in Gottingen. Mathematisch-Physikalische Klasse
pages 6–19.

Rijn, L. C. van, 1984. “Sediment transport, Part III: bed form and alluvial roughness.” Journal
of Hydraulic Engineering 110 (12): 1733–1754.

Rijn, L. C. van, 2007. “Unified View of Sediment Transport by Currents and Waves. I: Initiation
of Motion, Bed Roughness, and Bed-Load Transport.” Journal of Hydraulic Engineering
133 (6): 649–667.

Rijn, L. C. van, D. R. Walstra and M. v. Ormondt, 2004. Description of TRANSPOR2004 and

implementation in Delft3D-ONLINE. Tech. Rep. Z3748.10, WL | Delft Hydraulics, Delft, The
Netherlands.

Deltares 378 of 562

 References

Ris, R. C., 1997. Spectral Modelling of Wind Waves in Coastal Areas. Communications on
Hydraulic and Geotechnical Engineering, report 97-4. Delft University of Technology, Delft,
The Netherlands. Ph.D. thesis.

Rodi, W., 1984. “Turbulence models and their application in Hydraulics, State-of-the-art paper
article sur l’etat de connaissance.” IAHR Paper presented by the IAHR-Section on Funda-
mentals of Division II: Experimental and Mathematical Fluid Dynamics, The Netherlands.

Ryan, P. J., D. R. F. Harleman and K. D. Stolzenbach, 1974. “Surface Heat Loss From Cooling
Ponds.” Water Resources Research 10 (5): 930–938.

T
Schrama, E., 2007. “Tides. Lecture Notes AE4-876.”

Semtner Jr., A. J., 1976. “Numerical simulation of the Arctic Ocean circulation.” Journal of
Physical Oceanography 6 (4): 409–425.
AF
Slørdal, L. H., 1997. “The pressure gradient force in sigma-co-ordinate ocean models.” Inter-
national Journal Numerical Methods In Fluids 24: 987–1017.

Smith, S. D. and E. G. Banke, 1975. “Variation of the sea surface drag coefficient with wind
speed.” Quarterly Joournal of the Royal Meteorological Society 101: 665–673.

Soulsby, R., 1997. Dynamics of marine sands, a manual for practical applications. Thomas
Telford, London.

Soulsby, R. L., A. G. Davies, J. Fredsøe, D. A. Huntley, I. G. Jonnson, D. Myrhaug, R. R.

Simons, A. Temperville and T. J. Zitman, 1993a. “Bed shear stresses due to combined
waves and currents.” In Abstracts-in-depth of the Marine Science and Technology G8-M
DR

overall workshop, Grenoble., pages 2.1-1/2.1–4. EC.

Soulsby, R. L., L. Hamm, G. Klopman, D. Myrhaug, R. R. Simons and G. P. Thomas, 1993b.

“Wave-current interaction within and outside the bottom boundary layer.” Coastal Engineer-
ing 21: 41–69.

Speziale, C. G., R. Abid and E. C. Anderson, 1992. “Critical evaluation of two-equation models
for near-wall turbulence.” AIAA Journal 30: 324–331.

Stelling, G. S. and J. A. T. M. van Kester, 1994. “On the approximation of horizontal gradi-
ents in sigma co-ordinates for bathymetry with steep bottom slopes.” International Journal
Numerical Methods In Fluids 18: 915–955.

Swart, 1974. Offshore sediment transport and equilibrium beach profiles. Ph.D. thesis, Delft
University of Technology, Delft, The Netherlands. Delft Hydraulics Publ. 131.

Sweers, H. E., 1976. “A nomogram to estimate the heat exchange coefficient at the air-water
interface as a function of windspeed and temperature; a critical survey of some literature.”
Journal of Hydrology 30: –.

Uittenbogaard, R. E., J. A. T. M. van Kester and G. S. Stelling, 1992. Implementation of

three turbulence models in 3D-TRISULA for rectangular grids. Tech. Rep. Z81, WL | Delft
Hydraulics, Delft, The Netherlands.

UNESCO, 1981a. Background papers and supporting data on the international equation of
state 1980. Tech. Rep. 38, UNESCO.

UNESCO, 1981b. The practical salinity scale 1978 and the international equation of state of
seawater 1980. Tech. Rep. 36, UNESCO. Tenth report of the Joint Panel on Oceanographic
Tables and Standards (1981), (JPOTS), Sidney, B.C., Canada.

Deltares 379 of 562

 References

Velzen, E. H. van, P. Jesse, P. Cornelissen and H. Coops, 2003. Stromingsweerstand vege-

tatie in uiterwaarden. Tech. Rep. 2003.029, Rijkswaterstaat/RIZA.

Verheij, H., 2002. Modification breach growth model in HIS-OM. Tech. Rep. Q3299, WL | Delft
Hydraulics, Delft, The Netherlands. (in Dutch).

Wang, J., Q. Liu, M. Jin, M. Ikeda and F. J. Saucier, 2005. “A Coupled Ice-Ocean Model
in the Pan-Arctic and North Atlantic Ocean: Simulation of Seasonal Cycles.” Journal of
Oceanography 61: 213–233.

Winterwerp, J. C. and R. E. Uittenbogaard, 1997. Sediment transport and fluid mud flow.

T
Tech. Rep. Z2005, WL | Delft Hydraulics, Delft, The Netherlands.

Wüest, A. and A. Lorke, 2003. “Small-Scale Hydrodynamics in Lakes.” Annual Review of Fluid
Mechanics 35 (1): 373–412.
AF
Wunderlich, W. O., 1972. Heat and Mass Transfer Between a Water Surface and the Atmo-
sphere. Water Resources Research Laboratory Report 14, TVA (Tennessee Valley Author-
ity), Tennessee Valley Authority, Division of Water Control Planning, Engineering Labora-
tory, Norris, TN.
DR

Deltares 380 of 562

 A The master definition file

A.1 Overview of keywords generated by GUI

The mdu-file contains the key information of the flow model. Besides the names of the relevant
user specified files, such as the grid file and the external forcings file, the values of various
model parameters should be specified in the MDU-file. In Table A.1 the model parameter
settings are given as well as the associated default setting for these parameters that are
generated by the Graphical User Interface of D-Flow FM. If a model parameter has a unit,
then this unit will also be given in [ ] in the column of Description in this table.

T
The basename of the mdu-file, without .mdu, is also used as the model identification string,
and is often denoted as mdu_name throughout this User Manual. It is equivalent to Delft3D-
FLOW’s runid concept.
AF Keyword
Table A.1: Standard MDU-file with default settings.

Default setting Description

[general]
Program D-Flow FM Program.
Version 1.2.60 ←- Version number of computational kernel.
.64623M
MDUFormatVersion 1.08 File format version. Do not edit this.
GuiVersion 1.5.4.45545 Version number of GUI.
AutoStart 0 Autostart simulation after loading MDU or not (0=no,
1=autostart, 2=autostartstop).
DR

PathsRelativeToParent 0 Whether or not (1/0) to resolve file names (e.g. inside

the *.ext file) relative to their direct parent, instead of to
the toplevel MDU working dir.

[geometry]
NetFile <*_net.nc>. See Appendix B.
DryPointsFile Dry points file <*.xyz>, third column dummy z values,
or polygon file <*.pol>.
GridEnclosureFile Enclosure file <*.pol> to clip outer parts from the grid.
StructureFile File <*.ini> containing list of hydraulic structures. See
section C.12.
GulliesFile Polyline file <*_gul.pliz>, containing lowest bed level
along talweg x, y, z level.
RoofsFile Polyline file <*_roof.pliz>, containing roofgutter
heights x, y, z level.
WaterLevIniFile Initial water levels sample file <*.xyz>.
LandBoundaryFile Only for plotting.
ThinDamFile <*_thd.pli>, Polyline(s) for tracing thin dams.
FixedWeirFile <*_fxw.pliz>, Polyline(s) x, y, z, z = fixed weir top lev-
els (formerly fixed weir).
PillarFile <*_pillar.pliz>, Polyline file containing four colums
with x, y, diameter and Cd coefficient for bridge pillars.
UseCaching 1 Use caching for geometrical/network-related items (0:
no, 1: yes) (section C.15).
VertplizFile <*_vlay.pliz>), = pliz with x, y, Z, first Z = nr of layers,
second Z = laytyp.
AllowBndAtBifurcation 0 Allow 1d boundary node when connecting branch
leads to bifurcation (1: yes, 0: no).
(continued on next page)

Deltares 381 of 562

 The master definition file

(continued from previous page)

Keyword Default setting Description
ProflocFile <*_proflocation.xyz>) x, y, z, z = profile refnumber.
ProfdefFile <*_profdefinition.def>) definition for all profile nrs.
ProfdefxyzFile <*_profdefinition.def>) definition for all profile nrs.
ManholeFile File containing manholes (e.g. <*.dat>).
PartitionFile <*_part.pol>, polyline(s) x, y.
WaterLevIni 0. Initial water level [m AD].
Bedlevuni -5. Uniform bed level [m AD], (only if BedlevType>=3),

T
used at missing z values in netfile.
Bedslope 0. Bed slope inclination [-], sets zk = bedlevuni +
x*bedslope and sets zbndz = xbndz*bedslope.
BedlevType 3 1: at cell center (tiles xz, yz, bl, bob=max(bl)),
2: at face (tiles xu, yu, blu, bob=blu),
3: at face (using mean node values),
AF
Blmeanbelow -999.
4:
5:
6:
at face (using min node values),
at face (using max node values),
with bl based on node values.
if not -999d0, below this level [m] the cell centre
bedlevel is the mean of surrouding netnodes.
Blminabove -999. if not -999d0, above this level [m] the cell centre
bedlevel is the min of surrouding netnodes.
AngLat 0. Angle of latitude S-N [deg], 0=no Coriolis.
AngLon 0. Angle of longitude E-W [deg], 0=Greenwich Mean
Time.
Conveyance2D -1 -1:R=HU, 0:R=H, 1:R=A/P, 2:K=analytic-1D conv,
DR

3:K=analytic-2D conv.
Nonlin1D 1 Non-linear 1D volumes, applicable for models with
closed cross sections.
1=treat closed sections as partially open by using a
Preissmann slot,
2=Nested Newton approach,
3=Partial Nested Newton approach. (For a de-
scription of these methods, see (Deltares, 2025a,
??sec:nestedNewton).
Nonlin2D 0 Non-linear 2D volumes, only i.c.m. BedlevType=3
and Conveyance2D>=1.
slotw1D 0.001 Minimum slotwidth 1D [m].
slotw2D 0.001 Minimum slotwidth 2D [m].
dthdth1D 2. Uniform width for 1D profiles and 1d2d internal links
[m].
Uniformheight1D 3. Uniform height for 1D profiles and 1d2d internal links
[m].
Uniformwidth1Dstreetinlets 0.2 Uniform width for street inlets [m].
Uniformheight1Dstreetinlets 0.1 Uniform height for street inlets [m].
Uniformtyp1Dstreetinlets -2 Uniform cross section type for street inlets (1: circle, 2:
rectangle, -2: closed rectangle).
Uniformwidth1Droofgutterpipes 0.1 Uniform width for roof gutter pipes [m].
Uniformheight1Droofgutterpipes0.1 Uniform height for roof gutter pipes [m].
Uniformtyp1Droofgutterpipes -2 Uniform cross section type for type roof gutter pipes (1:
circle, 2: rectangle, -2: closed rectangle).
Sillheightmin 0.0 Fixed weir only active if both ground heights are larger
than this value [m AD].
Makeorthocenters 0 (1: yes, 0: no) switch from circumcentres to orthocen-
tres in geominit.
(continued on next page)

Deltares 382 of 562

 The master definition file

(continued from previous page)

Keyword Default setting Description
Dcenterinside 1. Limit cell center [-]; 1.0:in cell <-> 0.0:on c/g.
Circumcenter 1. Computation of circumcenter [-]; iterate each edge
- 1=internal netlinks; iterate each loop - 2=internal
netlinks, 3=all netlinks
Bamin 1E-06 Minimum grid cell area [m2 ], i.c.m. cutcells.
OpenBoundaryTolerance 3. Search tolerance factor between boundary polyline
and grid cells. [Unit: in cell size units (i.e., not meters)].
RenumberFlowNodes 1 Renumber the flow nodes (1: yes, 0: no).

T
Kmx 0 Number of vertical layers. NB. If kewyord Sigma-
GrowthFactor is used, then number of layers is deter-
mined by D-Flow FM [-].
Layertype 1 1= sigma-layers, 2 = z-layers, 3 = use VertplizFile.
Numtopsig 0 Number of sigma-layers on top of z-layers in case of
AF
SigmaGrowthFactor

dxmin1D
1.

0.001
z-sigma-layers.
Growth factor of z-Layer thickness starting below the
level specified by Dztopuniabovez till the bed [-].
Minimum 1D link length [m].
dxDoubleAt1DEndNodes true Whether a 1D grid cell at the end of a network has to
be extended with 0.5∆x.
ChangeVelocityAtStructures false Ignore structure dimensions for the velocity at hydraulic
structures, when calculating the surrounding cell cen-
tered flow velocities.
ChangeStructureDimensions true Change the structure dimensions in case these are in-
consistent with the channel dimensions.
DR

⋄ weirs, orifices, general structures:

1. In case the crest width exceeds the surface
width, the crest width is set to the surface width;
2. In case the crest level is lower than the bed
level, the crest level is set to the bed level.
⋄ bridges:
1. In case the crest width exceeds the surface
width, the crest width is set to the surface width;
2. In case the flow area of the bridge exceeds the
upstream flow area the flow area of the bridge is
set to the upstream flow area.
⋄ universal weirs: only the crest level is
checked and changed.
NOTE: It is strongly advised not to change this pa-
rameter (true). Since turning this option off can
lead to instabilities and unrealistic results.

[volumeTables]
useVolumeTables 0 Use volume tables for 1D grid cells (see ??) (0: no, 1:
yes).
increment 0.1 The height increment for the volume tables [m].
useVolumeTableFile 0 Read and write the volume table from/to file (0: no, 1:
yes).

[numerics]
CFLMax 0.7 Maximum Courant nr [-].
AdvecType 33 Adv type, 0=no, 33=Perot q(uio-u) fast, 3=Perot q(uio-
u).
(continued on next page)

Deltares 383 of 562

 The master definition file

(continued from previous page)

Keyword Default setting Description
AdvecCorrection1D2D 0 Advection correction of 1D2D link volume (0: regular
advection, 1: link volume au*dx, 2: advection on 1D2D
switched off.)
TimeStepType 2 0=only transport, 1=transport + velocity update, 2=full
implicit step_reduce, 3=step_jacobi, 4=explicit.
maxNonlinearIterations 100 Maximal iterations in non-linear iteration loop before a
time step reduction is applied.
setHorizontalBobsFor1d2d 0 Bobs are set to 2D bedlevel, to prevent incorrect stor-

T
age in sewer system (0: no, 1:yes).
Limtyphu 0 Limiter type for waterdepth in continuity eq., 0=no,
1=minmod,2=vanLeer,3=Koren,4=Monotone Central.
Limtypmom 4 Limiter type for cell center advection velocity, 0=no,
1=minmod,2=vanLeer,4=Monotone Central.
Limtypsa 4 Limiter type for salinity transport, 0=no, 1=min-
AF
Icgsolver 4 or 6
mod,2=vanLeer,4=Monotone Central.
Solver type, 4 = sobekGS + Saad-ILUD (default se-
quential), 6 = PETSc (default parallel), 7= CG+MILU
(parallel).
LogSolverConvergence 0 Print time step, number of solver iterations and solver
residual to diagnostic output (0: no, 1: yes).
Maxdegree 6 Maximum degree in Gauss elimination.
FixedWeirScheme 9 6 = semi-subgrid scheme, 8 = Tabellenboek, 9 = Ville-
monte (default).
FixedWeirContraction 1. flow width = flow width*FixedWeirContraction. [-]
Fixedweirtopwidth 3 Uniform width of the groyne part of fixed weirs [m].
DR

Fixedweirtalud 4 Uniform talud slope of fixed weirs.

Fixedweirtopfrictcoef Uniform friction coefficient of the groyne part of fixed
weirs [the unit depends on frictiontype].
FixedweirRelaxationcoef 0.6 Fixed weir relaxation coefficient for computation of en-
ergy loss.
FixedweirScheme1d2d 0 Fixed weir scheme for 1d2d links (0: same as fixed-
weirscheme, 1: lateral iterative fixed weir scheme).
Fixedweir1d2d_dx 50.0 Extra delta x for lateral 1d2d fixed weirs.
Izbndpos 0 Position of z boundary, 0=mirroring of closest cell (as
in Delft3D-FLOW), 1=on net boundary.
Tlfsmo 0. Fourier smoothing time on water level boundaries [s].
Slopedrop2D 0. Apply droplosses only if local bottom slope > Slope-
drop2D [m], <=0 =no droplosses.
Drop1D 0 Limit the downstream water level in the momentum
equation to the downstream invert level, BOBdown
∗
(ζdown = max (BOBdown , ζdown )).
Chkadvd 0.1 Check advection terms if depth < chkadvd [m].
Teta0 0.55 Theta (implicitness) of time integration [-], 0.5 < Theta
< 1.0.
cstbnd 0 Delft3D-FLOW type velocity treatment near bound-
aries for small coastal models (1) or not (0).
Maxitverticalforestersal 0 Forester iterations for salinity (0: no vertical filter for
salinity, > 0: max nr of iterations).
Maxitverticalforestertem 0 Forester iterations for temperature (0: no vertical filter
for temperature, > 0: max nr of iterations).
TransportAutoTimestepdiff 0 Auto Timestepdiff in Transport, (0 : lim diff, no lim Dt_tr,
1: no lim diff, lim Dt_tr, 2: no lim diff, no lim Dt_tr, 3:
implicit (only 2D)).
(continued on next page)

Deltares 384 of 562

 The master definition file

(continued from previous page)

Keyword Default setting Description
Implicitdiffusion2D 0 Implicit diffusion in 2D (0: no, 1:yes).
Turbulencemodel 3 0=no, 1 = constant, 2 = algebraic, 3 = k-epsilon, 4 =
k-tau.
Turbulenceadvection 3 0=no, 3 = horizontal explicit vertical implicit.
AntiCreep 0 Include anti-creep to suppress artifical vertical diffu-
sion (0: no, 1: yes).
DiagnosticTransport 0 No update of transport quantities, also known as diag-
nostic transport (0: no, 1: yes).

T
Maxwaterleveldiff 0. Upper bound [m] on water level changes, (<= 0: no
bounds). Run will abort when violated.
Maxvelocitydiff 0. Upper bound [m/s] on velocity changes, (<= 0: no
bounds). Run will abort when violated.
Maxvelocity 0. Upper bound [m/s] on velocity (<= 0: no bounds). Run
AF
Waterlevelwarn
Velocitywarn
0.
0.
will abort when violated.
Warning level [m AD] on water level (<= 0: no check).
Warning level [m/s] on normal velocity(<= 0: no check).
Velmagnwarn 0. Warning level [m/s] on velocity magnitude (<= 0: no
check).
MinTimestepBreak 0. Smallest allowed timestep [s], checked on a sliding av-
erage of several timesteps. Run will abort when vio-
lated.
Epshu 0.0001 Threshold water depth for wetting and drying [m].
EpsMaxlev 1d-8 Stop criterium for non linear iteration.
EpsMaxlevm 1d-8 Stop criterium for Nested Newton loop in non-linear it-
DR

eration.
FlowSolver generic1d2d3d Flow solver: generic1d2d3d (generic solver),
implicit1d (implicit 1D solver).

[physics]
UnifFrictCoef 0.023 Uniform friction coefficient (0: no friction) [the unit de-
pends on UnifFrictType].
UnifFrictType 1 Uniform friction type (0: Chezy, 1: Manning, 2: White-
Colebrook, 3: White-Colebrook in WAQUA).
UnifFrictCoef1D 0.023 Uniform friction coefficient in 1D links (0: no friction)
[the unit depends on UnifFrictType].
UnifFrictCoefLin 0. Uniform linear friction coefficient (0: no friction) [m/s].
Vicouv 0.1 Uniform horizontal eddy viscosity [m2 /s].
Dicouv 0.1 Uniform horizontal eddy diffusivity [m2 /s].
Vicoww 1.d-6 Background vertical eddy viscosity [m2 /s].
Dicoww 1.d-6 Background vertical eddy diffusivity [m2 /s].
Vicwminb 0. Minimum viscosity in production and buoyancy term
[m2 /s].
Xlozmidov 0. Ozmidov length scale [m], default=0.0, no contribution
of internal waves to vertical diffusion.
Smagorinsky 0.2 Add Smagorinsky horizontal turbulence [-]:
vicu = vicu + ( (Smagorinsky*dx)**2)*S.
Elder 0. Add Elder contribution [-]:
vicu = vicu + Elder*kappa*ustar*H/6); e.g. 1.0.
irov 0 Wall friction, 0=free slip, 1 = partial slip using wall_ks.
wall_ks 0. Nikuradse roughness [m] for side walls,
wall_z0=wall_ks/30.
Rhomean 1000. Average water density [kg/m3 ].
(continued on next page)

Deltares 385 of 562

 The master definition file

(continued from previous page)

Keyword Default setting Description
Idensform 2 Density calulation (0: uniform, 1: Eckart, 2: UNESCO,
3=UNESCO83, 13=3+pressure).
Ag 9.81 Gravitational acceleration [m/s2 ].
TidalForcing 0 Tidal forcing, if jsferic=1 (0: no, 1: yes).
Doodsonstart 55.565 Doodson start time for tidal forcing [s].
Doodsonstop 375.575 Doodson stop time for tidal forcing [s].
Doodsoneps 0.0 Doodson tolerance level for tidal forcing [s].

T
VillemonteCD1 1.0 Calibration coefficient for Villemonte [-]. Default = 1.0.
VillemonteCD2 10.0 Calibration coefficient for Villemonte [-]. Default = 10.0.
Salinity 0 Include salinity, (0: no, 1: yes).
InitialSalinity 0. Initial salinity concentration [ppt].
Sal0abovezlev -999. Salinity 0 above level [m].
AF
DeltaSalinity
BackgroundSalinity
-999.
30.
uniform initial salinity [ppt].
Background salinity for eqn. of state if salinity not com-
puted [psu].
Temperature 0 Include temperature (0: no, 1: only transport, 3: ex-
cess model of D3D, 5: composite (ocean) model).
InitialTemperature 6. Initial temperature [◦ C].
BackgroundwaterTemperature 20. Background water temperature for eqn. of state if tem-
perature not computed [◦ C].
Secchidepth 2. Water clarity parameter [m].
Stanton 0.0013 Coefficient [-] for convective heat flux ( ), if negative,
then Cd wind is used.
DR

Dalton 0.0013 Coefficient [-] for evaporative heat flux ( ), if negative,

then Cd wind is used.
SecondaryFlow 0 Secondary flow (0: no, 1: yes).
BetaSpiral 0. Weight factor [-] of the spiral flow intensity on flow dis-
persion stresses (0d0 = disabled).
BreachGrowth symmetric- ←- Method for distributing dam breach width over dam
asymmetric break flow links: symmetric, proportional, or
symmetric-asymmetric.

[wind]
ICdtyp 2 Wind drag coefficient type (1: Const, 2: Smith&Banke
(2 pts), 3: S&B (3 pts), 4: Charnock 1955, 5: Hwang
2005, 6: Wuest 2005, 7: Hersbach 2010 (2 pts), 8:
4+viscous).
Cdbreakpoints 6.3d-4 Wind drag breakpoints [-], e.g. 0.00063 0.00723.
7.23d-3
Windspeedbreakpoints 0. 100. Wind speed breakpoints [m/s], e.g. 0.0 100.0.
Rhoair 1.2 Air density [kg/m3 ].
computedAirdensity 0 Compute air density (0: no, 1: yes). Requires
quantities airpressure, airtemperature and dewpoint in
<ext>-file.
Stresstowind 0. Switch between Wind speed (=0) and wind stress (=1)
approach for wind forcing.
Relativewind 0. Wind speed [kg/m3 ] factor relative to top-layer water
speed*relativewind (0d0=no relative wind, 1d0=using
full top layer speed).
Windpartialdry 1 Reduce windstress on water if link partially dry, only for
BedlevType=3, 0=no, 1=yes (default).
(continued on next page)

Deltares 386 of 562

 The master definition file

(continued from previous page)

Keyword Default setting Description
PavBnd 0. Average air pressure on open boundaries [N/m2 ], only
applied if value > 0.
PavIni 0. Initial air pressure [N/m2 ], only applied if value > 0.

[grw]
Infiltrationmodel 0 Infiltration method (0: No infiltration, 1: Interception
layer, 2: Constant infiltration capacity, 3: model unsat-
urated/saturated (with grw), 4: Horton).

T
UnifInfiltrationCapacity 0 Uniform maximum infiltration capacity [m/s].

[hydrology]
InterceptionModel 0 Interception model (0: none, 1: on, via layer thickness).
AF
[time]
refDate 20010101 Reference date [yyyymmdd]. By default midnight is
taken (00h00m00s)
tZone 0. Data Sources in GMT are interrogated with time in min-
utes since refdat-Tzone*60 [min].
tUnit S Time units in MDU [D, H, M or S].
dtUser 300. User timestep in seconds [s] (interval for external forc-
ing update & his/map output).
dtNodal 21600. Time interval [s] for updating nodal factors in astronom-
ical boundary conditions.
DR

dtMax 30. Maximum timestep in seconds [s].

dtInit 1. Initial timestep in seconds [s].
tStart 0. Start time with respect to RefDate [Tunit].
tStop 86400. Stop time with respect to RefDate [Tunit].
startDateTime Computation start datetime (yyyymmddhhmmss),
when specified, overrides TStart.
stopDateTime Computation stop datetime (yyyymmddhhmmss),
when specified, overrides TStop.
updateRoughnessInterval 86400. Update interval for time dependent roughness param-
eters [s].
tStartTlfsmo TStart Start time with respect to RefDate of Fourier smoothing
time on water level boundaries [Tunit].
startDateTimeTlfsmo Computation start datetime with respect to RefDate
of Fourier smoothing time on water level bound-
aries (yyyymmddhhmmss), when specified, overrides
TStartTlfsmo.

[restart]
RestartFile Restart file, only from NetCDF-file, hence: either
*_rst.nc or *_map.nc.
RestartDateTime Restart time [yyyymmddhhmmss], only relevant but
obligatory in case of restart from *_map.nc.

[external forcing]
ExtForceFile Old format for external forcings file *.ext, link with
tim/cmp-format boundary conditions specification.
ExtForceFileNew New format for external forcings file *.ext, link with bc-
format boundary conditions specification. See sec-
tion C.6.2.
(continued on next page)

Deltares 387 of 562

 The master definition file

(continued from previous page)

Keyword Default setting Description
Rainfall Include rainfall, (0=no, 1=yes).
QExt Include user Qin/out, externally provided, (0=no,
1=yes).
Evaporation Include evaporation in water balance, (0=no, 1=yes).
WindExt Include wind, externally provided, (0=no, 1=reserved
for EC, 2=yes).

[trachytopes]

T
TrtRou N Flag for trachytopes (Y=on, N=off).
TrtDef File (*.ttd) including trachytope definitions.
TrtL File (*.arl) including distribution of trachytope defini-
tions.
DtTrt 60. Interval for updating of bottom roughness due to tra-
AF
[output]
chytopes in seconds [s].

Wrishp_crs 0 Writing cross sections to shape file (0=no, 1=yes).

Wrishp_dambreak 0 Writing dambreaks to shape file (0=no, 1=yes).
Wrishp_dryarea 0 Writing dry areas to shape file (0=no, 1=yes).
Wrishp_enc 0 Writing enclosures to shape file (0=no, 1=yes).
Wrishp_emb 0 Writing embankments file (0=no, 1=yes).
Wrishp_fxw 0 Writing fixed weirs to shape file (0=no, 1=yes).
Wrishp_gate 0 Writing gates to shape file (0=no, 1=yes).
DR

Wrishp_genstruc 0 Writing general structures to shape file (0=no, 1=yes).

Wrishp_obs 0 Writing observation points to shape file (0=no, 1=yes).
Wrishp_pump 0 Writing pumps to shape file (0=no, 1=yes).
Wrishp_src 0 Writing sources and sinks to shape file (0=no, 1=yes).
Wrishp_thd 0 Writing thin dams to shape file (0=no, 1=yes).
Wrishp_weir 0 Writing weirs to shape file (0=no, 1=yes).
OutputDir Output directory of map-, his-, rst-, dat- and timings-
files, default: DFM_OUTPUT_<modelname>. Set to .
for no dir/current dir.
WAQOutputDir Output directory of Water Quality files.
FlowGeomFile *_flowgeom.nc Flow geometry file in NetCDF format.
ObsFile Space separated list of files, containing information
about observation points. See section F.2.2.
DeleteObsPointsOutsideGrid 0 Delete observation points outside the grid (0=no,
1=yes).
CrsFile Space separated list of files, containing information
about observation cross sections. See section F.2.4.
FouFile Name of attribute file that defines the *_fou.nc Fourier
output file in NetCDF format, see C.14.
FouUpdateStep 0 Fourier output type: 0 = every user step ; 1 = every
computational step ; 2 = equal to his output.
HisFile *_his.nc History file in NetCDF format.
HisInterval 300. History output, given as ’interval’ ’start period’ ’end pe-
riod’ [s].
XLSInterval 0. Interval between XLS history [s].
MapFile *_map.nc Map file in NetCDF format.
MapInterval 1200. Map file output, given as ’interval’ ’start period’ ’end
period’ [s].
(continued on next page)

Deltares 388 of 562

 The master definition file

(continued from previous page)

Keyword Default setting Description
RstInterval 0. Restart file output, given as ’interval’ ’start period’ ’end
period’ [s].
ComInterval DtUser Comfile write times, given as ’interval’ ’start period’
’end period’ [s] w.r.t. Refdate
MapFormat 4 Map file format, 1: NetCDF, 2: Tecplot, 3: NetCDF and
Tecplot, 4: NetCDF UGRID.
NcFormat 3 Format for all NetCDF output files (3: classic, 4:
NetCDF4+HDF5).

T
NcMapDataPrecision double Precision for NetCDF data in map files (double or sin-
gle).
NcHisDataPrecision double Precision for NetCDF data in his files (double or sin-
gle).
NcCompression 0 Whether or not (1/0) to apply compression to NetCDF
output files - NOTE: only works when NcFormat = 4.
AF
NcWriteLatLon 0 Write extra lat-lon coordinates for all projected coordi-
nate variables in each NetCDF file (for CF-compliancy)
(1: yes, 0: no).
Several His file options See section F.3.1.
wriHis_balance 1 Write mass balance totals to his file, (1: yes, 0: no).
wriHis_structure_gen 1 Write general structure parameters to his file, (1: yes,
0: no).
wriHis_structure_dam 1 Write dam parameters to his file, (1: yes, 0: no).
wriHis_structure_pump 1 Write pump parameters to his file, (1: yes, 0: no).
wriHis_structure_gate 1 Write gate parameters to his file, (1: yes, 0: no).
DR

wriHis_structure_weir 1 Write weir parameters to his file, (1: yes, 0: no).

wriHis_sourcesink 1 Write sources-sinks statistics to his file, (1: yes, 0: no).
wriHis_turbulence 1 Write k, eps and vicww to his file, (1: yes, 0: no).
wriHis_wind 1 Write wind velocities to his file, (1: yes, 0: no).
wriHis_rain 1 Write precipitation to his file, (1: yes, 0: no).
wriHis_airdensity 0 Write air density to his file (1: yes, 0: no).
wriHis_infiltration 1 Write infiltration to his file, (1: yes, 0: no).
wriHis_temperature 1 Write temperature to his file, (1: yes, 0: no).
wriHis_waves 1 Write wave data to his file, (1: yes, 0: no).
wriHis_heat_fluxes 1 Write heat fluxes to his file, (1: yes, 0: no).
wriHis_salinity 1 Write salinity to his file, (1: yes, 0: no).
wriHis_density 1 Write density to his file, (1: yes, 0: no).
wriHis_waterlevel_s1 1 Write water level to his file, (1: yes, 0: no).
wriHis_bedlevel 1 Write bed level to his file, (1: yes, 0: no).
wriHis_waterdepth 0 Write water depth to his file, (1: yes, 0: no).
wriHis_velocity_vector 1 Write velocity vectors to his file, (1: yes, 0: no).
wriHis_upward_velocity_ ←- 0 Write upward velocity to his file, (1: yes, 0: no).
component
wriHis_sediment 1 Write sediment transport to his file, (1: yes, 0: no).
wriHis_constituents 1 Write tracers to his file, (1: yes, 0: no).
wriHis_zcor 1 Write vertical coordinates to his file, (1: yes, 0: no).
wriHis_taucurrent 1 Write mean bed shear stress to his file, (1: yes, 0: no).
wriHis_velocity 1 Write velocity magnitude to his file, (1: yes, 0: no).
wriHis_wqBot3d 0 Write 3D water quality bottom variables to his file, (1:
yes, 0: no).

(continued on next page)

Deltares 389 of 562

 The master definition file

(continued from previous page)

Keyword Default setting Description
Several Map file options See section F.3.2.
wriMap_waterlevel_s0 1 Write water levels at old time level to map file, (1: yes,
0: no).
wriMap_waterlevel_s1 1 Write water levels at new time level to map file, (1: yes,
0: no).
wriMap_evaporation 0 Write evaporation to map file, (1: yes, 0: no).
wriMap_velocity_component_u0 1 Write velocities at old time level to map file, (1: yes, 0:
no).

T
wriMap_velocity_component_u1 1 Write velocities at new time level to map file, (1: yes,
0: no).
wriMap_velocity_vector 1 Write cell-center velocity vectors to map file, (1: yes, 0:
no).
wriMap_upward_velocity_ ←- 0 Write upward velocity component to map file, (1: yes,
AF
component
wriMap_density_rho
wriMap_horizontal_ ←-
viscosity_viu
1
1
0: no).
Write density to map file, (1: yes, 0: no).
Write horizontal viscosity to map file, (1: yes, 0: no).

wriMap_horizontal_ ←- 1 Write horizontal diffusivity to map file, (1: yes, 0: no).

diffusivity_diu
wriMap_flow_flux_q1 1 Write fluxes to map file, (1: yes, 0: no).
wriMap_spiral_flow 1 Write spiral flow to map file, (1: yes, 0: no).
wriMap_numlimdt 1 Write numlimdt to map file, (1: yes, 0: no).
Wrixyz_numlimdt 0 Write numlimdt to xyz file, (1: yes, 0: no). This option
is useful when a map file is not written.
DR

wriMap_taucurrent 1 Write bottom friction to map file, (1: yes, 0: no).

wriMap_chezy 0 Write chezy roughness in flow elements to map file, (1:
yes, 0: no)
wriMap_chezy_on_flow_links 0 Write chezy roughness on flow links to map file, (1:
yes, 0: no)
wriMap_input_roughness 0 Write chezy input roughness on flow links to map file,
(1: yes, 0: no).
wriMap_turbulence 1 Write turbulence to map file, (1: yes, 0: no).
wriMap_rain 0 Write rainfall rate to map file, (1: yes, 0: no).
wriMap_wind 1 Write winds to map file, (1: yes, 0: no).
wriMap_airdensity 0 Write air density to map file, (1:yes, 0:no).
Writek_CdWind 0 Write wind friction coefficients to tek file (1: yes, 0: no).
wriMap_heat_fluxes 0 Write heat fluxes to map file, (1: yes, 0: no).
wriMap_fixed_weir_energy_loss 0 Write energy losses of fixed weirs to map file, (1: yes,
0: no).
wriMap_flow_analysis 0 Write flow analysis data to the map file (1:yes, 0:no).
wriMap_volume1 0 Write volumes to map file (1: yes, 0: no).
wriMap_waterdepth 1 Write water depths to map file (1: yes, 0: no).
wriMap_waterdepth_hu 0 Write water depths on u-points to map file (1: yes, 0:
no).
wriMap_ancillary_variables 0 Write ancillary variables attributes to map file (1: yes,
0: no).
wriMap_flowarea_au 0 Write flow areas au to map file (1: yes, 0: no).
wriMap_velocity_magnitude 1 Write cell-center velocity vector magnitude to map file
(1: yes, 0: no).
wriMap_velocity_vectorq 0 Write cell-center velocity vectors (discharge-based) to
map file (1: yes, 0: no).
(continued on next page)

Deltares 390 of 562

 The master definition file

(continued from previous page)

Keyword Default setting Description
wriMap_flow_flux_q1_main 0 Write flow flux in main channel to map file (1: yes, 0:
no).
wriMap_interception 0 Write interception to map file (1: yes, 0: no).
wriMap_windstress 0 Write wind stress to map file (1: yes, 0: no).
wriMap_CdWind 1 Write wind friction coeffs to tek file (1: yes, 0: no).
wriMap_DTcell 0 Write time step per cell based on CFL (1: yes, 0: no).
wriMap_bnd 0 Write boundary points to map file (1: yes, 0: no).

T
wriMap_Qin 0 Write sum of all influxes to map file (1: yes, 0: no).
wriMap_wqBot3d 0 Write 3D water quality bottom variables to map file (1:
yes, 0: no).
wriMap_every_dt 0 Write output to map file every computational timestep,
between start and stop time from MapInterval, (1:
yes, 0: no).
AF MapOutputTimeVector File (.mpt) containing fixed map output times (s) w.r.t.
RefDate.
ComOutputTimeVector File (.ctv) containing fixed comfile write times (s) w.r.t.
RefDate.
FullGridOutput 0 Full grid output mode for layer positions (0: compact,
1: full time-varying grid layer data).
EulerVelocities 0 Write Eulerian velocities, (1: yes, 0: no).
ClassMapFile Name of class map file.
WaterlevelClasses 0. Series of values between which water level classes are
computed.
DR

WaterdepthClasses 0. Series of values between which water depth classes

are computed.
ClassMapInterval 0 Interval [s] between class map file outputs.
WaqInterval 0. Interval [s] between DELWAQ file outputs.
StatsInterval -60. Interval [s] between screen step outputs in seconds
simulation time, if negative in seconds wall clock time.
TimingsInterval 0. Timings output interval TimingsInterval.
Richardsononoutput 0 Write Richardson number, (1: yes, 0: no).

Remarks:
⋄ HisInterval, MapInterval, RstInterval, ClassMapInterval, ComInterval
have been implemented such that all the intervals (in [s]) which are written (compared
to TStart, which is in TUnit should be a multiple of DtUser (in [s]).
⋄ Before Delft3D Flexible Mesh Suite 2024.03 wrong output times were skipped in the
output file, as a consequence. Currently the model simulation crashes if the intervals
are not a multiple of DtUser.

A.2 Overview of additional keywords for 3D Modelling

In the current D-Flow FM Graphical User Interface not all keywords can be specified for 3D
modelling yet. This means that still some keywords for 3D modelling have to be specified
manually. These keywords are shown in Table A.2. If a keyword has a unit, then this unit will
also be given in [ ] in the column of Description in this table.

Deltares 391 of 562

 The master definition file

Table A.2: Keywords in MDU-file for 3D modelling not in the GUI yet.

Keyword Default setting Description

[geometry]
ZlayBot -999 if specified, first z-layer starts from zlaybot [ ], if not, it
starts from the lowest bed point.
ZlayTop -999 if specified, highest z-layer ends at zlaytop [ ], if not, it
ends at the initial water level.
StretchType -1 Stretching type for non-uniform layers, 1=user defined,
2=exponential, otherwise=uniform.

T
StretchCoef coefficients for sigma layer, 1: Percentages of the lay-
ers, user defined, laycof(kmx), 2: Stretching level, and
two coefficients for layers growth, laycof(3).
[numerics]
HorizontalMomentumfilter 0 Filter for reduction of checkerboarding; 0=No, 1=yes.
Checkerboardmonitor Flag for checkerboarding output on history file (only for
AF Tspinupturblogprof
0

0.0
sigma layers yet); 0=No, 1=yes.
Spin up time [s] when starting with a parabolic viscosity
profile in whole model domain.
Vertadvtypmom 6 Vertical advection type in momentum equation; 3: Up-
wind implicit, 6: centerbased upwind explicit.
Vertadvtypsal 6 Vertical advection type for salinity (0: none, 4: Theta
implicit, 6: higher order explicit, no Forester filter).
Noted that Vertadvtypsal=4 leads to less numerical
dissipation than Vertadvtypsal=6 (default).
Vertadvtyptem 6 Vertical advection type for temperature (0: none, 4:
Theta implicit, 6: higher order explicit, no Forester
DR

filter). Noted that Vertadvtyptem=4 leads to less

numerical dissipation than Vertadvtyptem=6 (de-
fault).
Zerozbndinflowadvection 0 Switch for advection at open boundary (0: Neumann,
1=zero at inflow, 2=zero at inflow and outflow).

A.3 Overview of research keywords

In Table A.1 and Table A.2 in this appendix an overview of keywords in the master definition
file is given that can be specified by the user or should be added manually, respectively. In
addition there are several research keywords in the computational kernel of D-Flow Flexible
Mesh that should, in principle, not be used and not be changed by the user. These keywords
haven’t been documented yet and aren’t tested in the D-Flow FM test benches yet. Therefore,
using the default setting of these research keywords is strongly recommended. Because
these keywords are listed in the diagnostic file, for the sake of completeness they are listed in
the table below and also in Section 5.12 of the D-Flow FM Technical Reference Manual. If a
keyword has a unit, then this unit will also be given in [ ] in the column of Description in this
table.

Table A.3: Overview of numerical research parameters with compulsory defaults.

Keyword Default setting Description

[geometry]
(continued on next page)

Deltares 392 of 562

 The master definition file

Keyword Preferred Description

setting
(continued from previous page)
stripMesh 0 Flag specifying whether grid nodes and edges not con-
nected to active grid cells/faces should be removed
from the administration, 0 = no, 1 = yes. This option is
only relevant in sequential mode; the partitioning step
of a parallel run always performs this action. Switching
this on reduces the clutter in the output map-file and
simplifies data exchange via BMI.

T
[numerics]
Barocterm 4 Various options for baroclinic pressure term.
BaroctimInt 4 Time integration baroclinic pressure, 1 = explicit, 4 =
Adams Bashforth + dryfloodproof.
AF
Cffacver

Corioadamsbashfordfac
0.

0.5
Factor for including (1-CFL) in HO term vertical (0d0:
no, 1d0: yes).
Adams Bashforth factor for Coriolis term.
Drop3D 1 Apply drop losses in 3D if z upwind is below bob + 2/3
hu*drop3D (0: no, 1: yes).
Horadvtypzlayer 0 Horizontal advection treatment of z-layers for dam
breaks (0: default, 2: sigma-like).
Icoriolistype 5 0=No, 1=yes, if jsferic then spatially varying, 2-5: ..., if
icoriolistype==6 then constant (anglat).
Jbasqbnddownwindhs 0 0=original hu on qbnd, 1=downwind hs on qbnd.
Filterorder 2 First-order or second order filter to suppress checker-
DR

boarding.
Keepstbndonoutflow 0 Keep salinity and temperature signals on boundary
also at outflow, (1: yes, 0: no) (copy inside value on
outflow).
Keepzlayeringatbed 2 Z layering at bed: 0=original bed level, 1=adapted bed
level, 2= Ztbml approach of Delft3D-FLOW.
Logprofatubndin 1 ubnds inflow: 0=uniform U1, 1 = log U1, 2 = user3D.
Logprofkepsbndin 0 inflow: 0=0 keps, 1 = log keps, 2 = user3D.
Newcorio 1 Temporary keyword for Coriolis improvement on open
boundary; 0=No, 1=yes.
TestDryingFlooding 0 Drying flooding algorithm (0: D-Flow FM, 1: Delft3D-
FLOW, 2: Similar to 0, and volume limitation in the
transport solver based on Epshu).
Turbulenceadvection 3 Turbulence advection (0: none, 1=Upwind explicit,
2=Central explicit, 3: horizontally explicit and vertically
implicit, 4=Central implicit.
Windhuorzwsbased 0 Wind approach; 0= Hu-based (Delft3D-FLOW), 1= fi-
nite volume based.

[calibration] Roughness calibration. Details in Chapter 14.

UseCalibration 0 Activate calibration factor friction multiplier (0: no, 1:
yes).
DefinitionFile File (*.cld) containing calibration definitions. Details in
Section C.9.1.
AreaFile File (*.cll) containing area distribution of calibration def-
initions. Details in Section C.9.2.

(continued on next page)

Deltares 393 of 562

 The master definition file

Keyword Preferred Description

setting
(continued from previous page)

[processes] Online water quality processes. Details in Chapter 18.

SubstanceFile Substance file name. Details in Section 18.3.2.
AdditionalHistoryOutputFile Extra history output filename. Details in Sec-
tion 18.3.6.
StatisticsFile Statistics definition file. Details in Section 18.3.6.
ThetaVertical 0.0 Theta value for vertical transport of water quality sub-

T
stances [-].
DtProcesses 0.0 waq processes time step [s]. Must be a multiple of
DtUser. If DtProcesses is negative, water quality pro-
cesses are calculated with every hydrodynamic time
step.
AF ProcessFluxIntegration

VolumeDryThreshold
1

1d-3
Process fluxes integration option (1: WAQ, 2: D-Flow
FM).
Volume [m3 ] below which segments are marked as dry.
Details in Section 18.3.5.
DepthDryThreshold 1d-3 Water depth [m] below which segments are marked as
dry. Details in Section 18.3.5.

[veg] Dynamic vegetation model, more details in Sec-

tion 13.3.
Vegetationmodelnr 0 Vegetation model nr, (0: no, 1: Baptist DFM).
DR

Clveg 0.8 Stem distance factor [-].

Cdveg 0.7 Stem Cd coefficient [-].
Cbveg 0.0 Stem stiffness coefficient [-].
Rhoveg 0.0 Stem Rho, if > 0, bouyant stick procedure [kg/m3 ].
Stemheightstd 0.0 Stem height standard deviation fraction, e.g. 0.1 [-].
Densvegminbap 0.0 Minimum vegetation density in Baptist formula. Only in
2D. [1/m2 ].
If expchistem < 0
Expchistem 0 [-]
Expchileaf 0 [-]
Uchistem 0 [m/s]
Uchileaf 0 [m/s]
Arealeaf 0 [m2 ]
Cdleaf 0 [-]

Note: The data block [processes] for online water quality processes is not valid for D-
Flow FM 1D2D, because this module doesn’t have a water quality component yet.

A.4 Overview of deprecated and removed keywords

The following table lists in alphabetical order per data block the deprecated keywords (which
are currently still supported by D-Flow FM, but may be removed in a future release) and the
removed keywords (which are no longer processed). When the functionality of the keyword
has is now supported via another keyword then the new keyword is specified. Check the
description of the new keyword in Table A.1 for more details on how to use it.

Deltares 394 of 562

 The master definition file

Table A.4: Overview of deprecated and removed keywords.

Keyword Action
[Geometry]
bathymetryFile Removed since March 2022.
See [Geometry] keyword bedLevelFile in this table.
bedLevelFile Removed since March 2022.
Use [Geometry] keyword iniFieldFile instead. That key-
word should point to a file with the following content where
my_bedlevel_data.xyb is the name of your bed level samples
file which was originally referenced by the removed keyword.

T
[General]
fileVersion = 2.00
fileType = iniField

[Initial]
AF quantity
dataFile
dataFileType
interpolationMethod
=
=
=
=
bedlevel
my_bedlevel_data.xyb
sample
triangulation
BotLevUni Removed since March 2022.
Use [Geometry] keyword bedLevUni instead.
botLevType Removed since March 2022.
Use [Geometry] keyword bedLevType instead.
manholeFile Removed since March 2022.
Use [Geometry] keyword storageNodeFile instead.
noOptimizedPolygon Removed since March 2022. Option no longer supported.
thindykeFile Removed since March 2022. Use [Geometry] keyword
DR

fixedWeirFile instead.
old format of general Removed since October 2023. Use new keywords instead.
structure The old/new keywords are: widthleftW1/upstream1Width, lev-
elleftZb1/upstream1Level, widthrightW2/upstream2Width, lev-
elrightZb2/upstream2Level, widthleftWsdl/downstream1Width,
levelleftZbsl/downstream1Level, widthrightWsdr/downstream2Width,
levelrightZbsr/downstream2Level, widthcenter/crestWidth, lev-
elcenter/crestLevel, gateheight/gateLowerEdgeLevel, gate-
doorheight/gateHeight, door_opening_width/gateOpeningWidth,
lower_edge_level/gateLowerEdgeLevel, open-
ing_width/gateOpeningWidth, sill_level/crestLevel, door_height/gateHeight,
horizontal_opening_direction/gateOpeningHorizontalDirection,
crest_level/crestLevel.

[Numerics]
hkad Removed since March 2022.
Option no longer supported.
iThinDykeScheme Removed since March 2022.
Use [Numerics] keyword fixedWeirScheme instead.
thinDykeContraction Removed since March 2022.
Use [Numerics] keyword fixedWeirContraction instead.
transportTimeStepping Removed since August 2022. Option no longer supported.
transportMethod Removed since August 2022.
Value 1 is the default and only available option, no further input
needed. Value 2 for diagnostic transport is now under its own keyword.
Use [Numerics] keyword diagnosticTransport=1 instead.

[Output]
(continued on next page)

Deltares 395 of 562

 The master definition file

Keyword Action
(continued from previous page)
writeBalanceFile Removed since March 2022.
Superseded by default information included in the history file.

[Processes]
wriWaqBot3dOutput Removed since August 2024.
Replaced by fine-grained [Output] keywords wriHis_wqBot3d
and wriMap_wqBot3d.

T
AF
DR

Deltares 396 of 562

 B The net file for flexible meshes
The net file contains the full computational grid (mesh) information. It is a netCDF file that can
contain 2D grids, as well as 1D networks, and combinations of these. The netCDF conven-
tions used for this file are:
⋄ CF-conventions (≥ 1.7) and UGRID-1.0 for the 2D grids. More information on: http://
ugrid-conventions.github.io/ugrid-conventions/.

B.1 2D grids in netCDF UGRID files

T
D-Flow FM reads net files that adhere to the 2D rules in the UGRID conventions. At the
minimum this means that the file must contain the mesh node coordinates and for all grid cells
AF (’faces’) the corner node numbers in the face_node_connectivity table.
DR

Deltares 397 of 562

 C Attribute files

C.1 Introduction
In the following sections we describe the attribute files used in the input file (MDU-file) of D-
Flow FM. Most of these files contain the quantities that describe one specific item, such as the
location of open boundaries, or time dependent data of fluxes discharged in the model area
by discharge stations. Most of the attribute files can be generated by the D-Flow FM GUI after
defining an input scenario. Some files can almost only be generated by utility programs such
as the unstructured grid generated by the Grid Editor. Still, we describe both type of files as

T
it might be useful to know how the input data is structured to be able to generate (large) files,
such as astronomic boundary conditions, or time-series for wind speed and direction by client
specific tools.

C.2 Polyline/polygon file

AF D-Flow FM uses the same format for polylines and (closed) polygons. When used as a poly-
gon file, there is not the requirement that the first and last point should be identical. It is
good modelling practice to name files containing polygons with the extension <.pol>, and
files containing polylines with the extension <.pli>. When the polylines have a third column
with z -coordinates, the extension <.pliz> is advised.

File contents The coordinates of one or more polylines. Each polyline (piecewise
linear) is written in a single block of data.
Filetype ASCII
File format Free formatted
Filename <name.pol>
DR

Generated RGFGRID, QUICKIN, D-Flow FM GUI, etc

Record description:

Record Record description

Preceding description records, starting with an asterisk (∗), and will

be ignored.

1 A non blank character string, starting in column one.

2 Two integers Nr , Nc representing the numbers of rows and number

of columns for this block of data.

Two reals representing the x, y or λ, ϕ-coordinate, followed by re-

maining data values at that location (if Nc > 2).

Example:

*
* Polyline L007
*
L007
6 2
132400.0 549045.0
132345.0 549030.0
132165.0 549285.0
131940.0 549550.0
131820.0 549670.0

Deltares 398 of 562

 Attribute files

131585.0 549520.0
*
* Polyline L008
*
L008
4 2
131595.0 549685.0
131750.0 549865.0
131595.0 550025.0
131415.0 550175.0
*
* Polyline L009

T
*
L009
6 2
131595.0 549655.0
148975.0 564595.0
150000.0 564935.0
AF 152105.0
153150.0
154565.0
565500.0
566375.0
567735.0

C.3 Sample file

Sample file are used for several of D-Flow FM’s input files.

File contents The location and value of samples.

Filetype ASCII
File format Free formatted
Filename <name.xyz>
DR

Generated Manually or Offline with QUICKIN or D-Flow FM GUI and data from
digitised charts or GIS-database.

Record description:

Filetype Record description

Free formatted Location and sample value per row

Two reals representing the x, y or λ, ϕ-coordinate and one real rep-
resenting the sample value

Example:

Sample file with 12 sample values with their location (free formatted file).

213813.2 603732.1 -4.053000

214686.0 607226.1 -4.522000
214891.7 610751.2 -5.000000
210330.8 601424.1 -2.169000
211798.0 604444.8 -2.499000
212460.0 607475.7 -2.760000
212436.9 610362.5 -2.865000
185535.4 606607.9 1.360000
186353.0 603789.4 1.122000
187959.2 601197.6 0.9050000
190193.0 599101.5 0.7050000
208578.7 602513.7 -0.7990000

Deltares 399 of 562

 Attribute files

C.4 Time series <tim> file (ASCII)

Warning:
⋄ Deprecated: The ASCII <tim> format is a legacy file format without any metadata. It
is recommended to use the <bc> format instead (see Section C.5).

Time series files are used for several of D-Flow FM’s input files. There is no header, except
for optional comment lines (starting with * or #). There should be two or more columns
containing numbers (integer or floating point): the first column contains time in minutes since
the model’s reference date, all remaining columns contain the data values. Columns can be

T
separated using one or more whitespace or tab characters. Each line contains a single time
with its (space-uniform) values. A simple example is shown below:

* comments
0 1.23
AF 60 1.5
* ...
1440 1.5

C.5 Time-varying data <bc> file (ASCII)

Time-varying input is used in several places, for example for Boundary Conditions. The
<*.bc> file format was initially introduced for one specific purpose, but its use has since
expanded. Now, <*.bc> files can generally be used as well for meteorological forcings,
hydraulic structure control, laterals, source-sinks, and time-varying parameter input (cf. Ap-
pendix D). The external forcings file may point to this type of file via the forcingFile
DR

keyword (see section C.6.2). Similary, a structure INI file may refer to this type of file for the
individual hydraulic structure (geometrical) parameters (see Section C.12.13).

The time-varying data may be provided as timeseries or as periodic signals (see harmonic
and astronomic in Table C.1.

The <*.bc> format enables the combination of multiple forcing signals within a single ASCII
file. Multiple Boundary, Meteo, Lateral, SourceSink blocks in the external forcings file can
reference the same file. Similarly, all hydraulic structure dynamics can be collected in the
same file, although this is optional and left for the modeller to decide.

The file consists of a General block followed by one or more Forcing blocks. Each forcing
block consists of a column-wise table (the data) and a header specifying how this table should
be interpreted. A wide range of functions and forcings data is supported, so care must be
taken to provide correct and complete header data.

Table C.1: Description of <bc> format.

Keyword Type Default Description

[General]
fileVersion String 1.01 File version. Do not edit this.
fileType String boundConds File type. Do not edit this.

[Forcing] Repeat as needed

(continued on next page)

Deltares 400 of 562

 Attribute files

Keyword Type Default Description

(continued from previous page)
name String Location name. Possible values are:
⋄ global: Spatially uniform values,
e.g., for meteo forcing.
⋄ <polyline point>: Boundary
polyline (point) reference.
⋄ <location Id>: Location id, e.g.,
for meteo stations, hydraulic struc-

T
tures and other "point" locations.
More details for each of these options can
be found in Section C.5.1.
function String Functiontype. The supported
AF options
harmonic,
are

harmonic-Correction,
timeSeries,
astronomic,

astronomic-Correction, t3D,
QHTable, and constant. More details
for each of these options can be found in
Section C.5.2.
offset Double 0 If function equals timeSeries, t3D
or constant all values in the table are
increased by the offset (after multiplica-
DR

tion by factor).
factor Double 1 If function equals timeSeries, t3D
or constant all values in the table are
multiplied with the factor. If function
equals harmonic or astronomic)
only the amplitude column is multiplied by
the given factor.
Vertical Position Double[] The vertical position is specified as a
Specification space- or comma-separated list of floats,
the interpretation of which varies accord-
ing to the vertical position type. The or-
der of the positions in the list becomes
relevant when referring to them from the
quantity blocks. However, no specific or-
dering of these positions (ascending or
descending) is assumed.
Vertical String Possible values are:
Interpolation
⋄ linear: linear interpolation between
vertical positions.
⋄ log: logarithmic interpolation be-
tween vertical positions (e.g. vertical
velocity profiles).
⋄ block: equal to the value at the di-
rectly lower specified vertical position.
(continued on next page)

Deltares 401 of 562

 Attribute files

Keyword Type Default Description

(continued from previous page)
Vertical Position String Possible values are:
Type
⋄ percBed: Percentage [0-100%] or
Fraction [0-1] w.r.t. water depth from
the bed upward.
⋄ ZDatum: z -coordinate with respect to
the reference level of the model.
⋄ ZBed: Absolute distance from the bed

T
upward.
⋄ ZSurf: Absolute distance from the
free surface downward.
Time String Possible values are:
AF
Interpolation
⋄ linear: linear interpolation between
times.
⋄ Block-From: equal to that at the
start of the time interval (latest spec-
ified time value).
⋄ Block-To: equal to that at the end
of the time interval (upcoming speci-
fied time value).
⋄ amountToRate: Input data is in-
terpreted as absolute amount (e.g.,
DR

millimeters) in past time interval, and

returned as an average rate in that
time interval (e.g., millimeters/sec-
ond). Typically used for (but not re-
stricted to) rainfall quantity.

The next three keywords repeated for every column in this data block
quantity String Name of quantity, directly related to which
type of (forcing) data is provided here.
More details about all supported quanti-
ties can be found in Section C.5.3.
unit String Unit of quantity
Vertical Position Integer This is a (one-based) index into the
vertical-position-specification, assigning a
vertical position to the quantity (t3D-
blocks only)

The data block

... This block holds the actual data in columns. The interpretation of the
columns is determined by the order of the aforementioned quantity
keywords, i.e. the n-th quantity-block refers to the n-th column. The
columns should contain valid floating point numbers (scientific notation
is allowed). The only exception is the Astronomic Component
column, which should contain strings representing the component
names.

Deltares 402 of 562

 Attribute files

C.5.1 Name in a bc block

The name keyword in the above Table C.1 depends on the type of forcing. The following
subsections define the details for each of these.

C.5.1.1 Global forcings

The location name global is reserved for a global, spatially uniform forcing signal, e.g.,
uniform rainfall.

T
Example:

<*.ext> file block: <*.bc> file Forcing block:

[Forcing]
AF [Meteo]
quantity = rainfall
name
function =
quantity =
unit
=

=
global
timeSeries
time
minutes since 2006-12-25 0:00:00
forcingFile = meteo.bc quantity = rainfall_rate
# ... unit = mm day-1

C.5.1.2 Boundary forcings

Boundary conditions can be prescribed by one or more Forcing blocks, each of which is
uniquely tied to an individual boundary support point. For a boundary location defined as
a polyline, the support points are the ones listed in the <.pli>-file. In that case the name
DR

in the bc-file should read <polyline label>_<point number>. The polyline label
is defined in the first header line of the <*.pli> file. The point number should be formatted
as a 4-digit zero-padded number. It is not needed to provide a Forcing block for all polyline
points. In particular, when only a single block is provided, for example for point number 0001,
the boundary signal is constant in space along the entire boundary polyline. Blocks with
the function QHTable are an exception to this rule, because in qh-boundaries no data is
required for individual support points. For this specific type of boundary condition, the name
in the <.bc>-file should read <polyline label> without any point number.

Example:

<*.ext> file block: <*.bc> file Forcing block:

(See page 405 for a complete example.)
[Boundary]
locationFile = upstream.pli [Forcing]
forcingFile = boundaries.bc name = left01_0001
# ...

<upstream.pli> file:

left01
12 2
30571.716797 30301.445312
30585.171875 30315.066406
...

Deltares 403 of 562

 Attribute files

C.5.1.3 Meteo forcings on stations

Future functionality: Time series for meteorological forcings may be specified for individual
locations, after which some spatial interpolation should be done. The name should specify
the <stationId>, but additionally x- and y- coordinates must be specified. Currently, as
the only alternative, station time series from netCDF files must be used. See Section E.2.4
for more details.

C.5.1.4 Forcings on "point" locations

Time series on independent objects/locations should be provided with the <*.bc> block name

T
keyword equal to the <*.ext>/structure INI block id keyword to uniquely identify each objec-
t/location. This holds for lateral discharges and source-sinks, as well as hydraulic structures.

Example:
AF <*.ext> file block: <*.bc> file Forcing block:

[Forcing]
name = sourcesinkABC
function = timeseries
timeInterpolation = linear
quantity = time
[SourceSink] unit = minutes since 2006-12-25 0:00:00
id = sourcesinkABC quantity = sourcesink_discharge
discharge = sources.bc unit = m3 s-1
salinityDelta = sources.bc quantity = sourcesink_salinityDelta
# ... unit = ppt
DR

See page 441 for a complete example for a hydraulic structure.

C.5.2 Function in a bc block

The function keyword specifies how the Forcing block should be interpreted. The function
also affects which quantity-unit pairs should be present in the header. The possible val-
ues for the function are:

timeSeries Value[s] as a function of time. One of the quantities must be

called Time (see remarks below for unit).
harmonic Period, amplitude, phase. One of the quantities (e.g., the first
one) must be called Harmonic Component [-]. The first
colum is the period in minutes. The other quantities should
come in pairs:
⋄ <quantity> amplitude (the unit depends on the
quantity)
⋄ <quantity> phase (degrees)
astronomic Component-name, amplitude, phase. One of the quantities
must be called Astronomic Component [-]. The other
quantities should come in pairs:
⋄ <quantity> amplitude (the unit depends on the
quantity)
⋄ <quantity> phase (degrees)

Deltares 404 of 562

 Attribute files

Harmonic-Correction Period, amplitude-factor, phase-offset. One of the quanti-

ties must be called Harmonic Component [-]. The other
quantities should come in pairs:
⋄ <quantity> amplitude (the unit depends on the
quantity)
⋄ <quantity> phase (degrees)
Astronomic-Correction Component-name, amplitude-factor, phase-offset. One of the
quantities must be called Astronomic Component [-].

T
The other quantities should come in pairs:
⋄ <quantity> amplitude (the unit depends on the
quantity)
⋄ <quantity> phase (degrees)
t3D Values on multiple vertical positions versus time. One of the
AF
QHTable
quantities must be called Time (see remarks below for unit).
Discharge as a function of water level. The quantities defini-
tion should be exactly the following two:
⋄ <quantity> waterLevel [m]
⋄ <quantity> discharge [m3 /2]
constant Constant value

Remarks:
DR

⋄ Although typical files will use UpperCamelCase keywords for chapters and lowerCamel-
Case for keywords and constants, all strings (including user-defined location and quan-
tity names) will be verified by case insensitive comparison.
⋄ Valid time units are string indicating the time unit (days, hours, minutes, or seconds)
since a reference date (YYYY-MM-DD) and optional time (HH-MM-SS) and time zone
(+/-HH). As in ISO 6801, T may be used between date and time; Z may be used as
time zone indicator.
⋄ All quantities in a harmonic or astronomic block are forced using the same components.
All quantities in a time series block are forced using the same time points.

Example:

[General]
fileVersion = 1.01
fileType = boundConds

[Forcing]
name = left01_0001
function = Harmonic
quantity = Harmonic Component
unit = -
quantity = waterlevelbnd amplitude
unit = m
quantity = waterlevelbnd phase
unit = rad/deg/minutes
0.0 4.114 0.0

[Forcing]
name = left01_0001
function = Harmonic
quantity = Harmonic Component
unit = -

Deltares 405 of 562

 Attribute files

quantity = normalvelocitybnd amplitude

unit = m/s
quantity = normalvelocitybnd phase
unit = rad/deg/minutes
0.0 1.215 0.0

[Forcing]
name = right01_0001
function = TimeSeries
timeInterpolation = Linear
quantity = time
unit = minutes since 2001-01-01

T
quantity = waterlevelbnd
unit = m
0.000000 2.50
AF 1440.000000 2.50

C.5.3 Quantity names in a bc block

The quantity keywords specify for each data column the specific quantity that it con-
tains. Most quantities will be the actual data quantities (more on that in the table below),
but typically the first quantity concerns the time dimension; the possible values for this are
time, harmonic component and astronomic component, all explained before in
Section C.5.2. The remainder of this section concerns the actual data quantities.

The name of a quantity is uniquely determined by the type of forcing (e.g. waterlevelbnd),
and—in case of "objects/locations"—also a specific parameter of that object (e.g.
sourcesink_discharge). The table below lists all possible values:
DR

Table C.3: Quantity names for use in <*.bc> files.

Forcing type/object parameter Quantity name in <*.bc> header

Boundary conditions
All quantities listed in Table C.9 for Identical to <*.ext> quantity value, e.g.,
boundary conditions. waterlevelbnd.
Lateral discharges
discharge lateral_discharge
Meteorological forcings
All quantity names listed in Table C.9 Identical to <*.ext> quantity value, e.g.,
for meteorological fields. airpressure.
Source and sinks
discharge sourcesink_discharge
salinityDelta sourcesink_salinityDelta
temperatureDelta sourcesink_temperatureDelta
sedFrac<fractionname>Delta sourcesink_sedFrac<fractionname>Delta
tracer<tracername>Delta sourcesink_tracer<tracername>Delta
Hydraulic structures
weir
crestLevel weir_crestLevel
(continued on next page)

Deltares 406 of 562

 Attribute files

Forcing type/object parameter Quantity name in <*.bc> header

(continued from previous page)
culvert
valveOpeningHeight culvert_valveOpeningHeight
pump
capacity pump_capacity
orifice

T
crestLevel orifice_crestLevel
gateLowerEdgeLevel orifice_gateLowerEdgeLevel
gate
crestLevel gate_crestLevel
AF gateLowerEdgeLevel
gateOpeningWidth
generalStructure
gate_gateLowerEdgeLevel
gate_gateOpeningWidth

crestLevel general_structure_crestLevel
gateLowerEdgeLevel general_structure_gateLowerEdgeLevel
gateOpeningWidth general_structure_gateOpeningWidth
damBreak
No <*.bc> support yet.
DR

C.6 The external forcings file

Two definition files for the external forcings are supported, each with their own format.

C.6.1 Old style external forcings

The name of the file is specified in the MDU-file as ExtForceFile. External forcings are
specified in in blocks key-value pairs, e.g.

* comments
* comments

QUANTITY =waterlevelbnd
FILENAME =tfl_01.pli
FILETYPE =9
METHOD =3
OPERAND =O

QUANTITY = ...
FILENAME = ...
...

The format is not case-sensitive, but key-value pairs are expected in the particular order

The majority of the keywords speak for themselves or are optional. The operand needs
some explanation. This keyword determines the operation to be performed with a new con-
nected forcing for a quantity already set by another forcing from a different source: ’O’ to
replace the existing value with the new one and ’+’ to add the new to the existing value.
Though generally applicable to all external forcings, it is most commonly used when working

Deltares 407 of 562

 Attribute files

with spatial fields (such as wind and atmospheric pressure) originating from different types of
sources. For instance a spatially uniform wind field could be set as a timeseries, but over-
written locally by a values interpolated from regional atmospheric model output, upon which
a cyclone is superimposed from a spiderweb-type file. This means that the <ext>-file likely
has three entries for quantity wind in the aforementioned order: a uniform timeseries with an
operand ’O’, a netCDF file with operand ’O’ and a spiderweb file with operand ’+’. The netCDF
file might not cover the entire flow grid. In the uncovered regions, the value from the uniform
wind is left unaltered. The same is done in the case of the spiderweb file with operand ’O’.
Regions for which data is missing in spatial fields are treated as non-existent in the file (cur-
rently no interpolation is by default active to fill gaps, therefore it is highly recommendable to

T
complete these files in a preprocessing step). In netCDF files, missing data are recognized
as values equal to the fill value designated in the _FillValue-attribute. In files for the
Curvi-type (ASCII) it is the NODATA-value in the header.

A comprehensive list of keywords is given in the table below.

AF
DR

Deltares 408 of 562

 Attribute files

quantity character Name of the quantity, see the list below

filename character File associated with this forcing
∗
varname character Variable name used in filename asso-
ciated with this forcing; some input files
may contain multiple variables
sourcemask∗ character File containing a mask
filetype integer Indication of the filetype:
1. Time series (C.4)

T
2. Time series magnitude and direction
3. Spatially varying weather
4. ArcInfo
5. Spiderweb data (cyclones) (C.13.3)
6. Curvilinear data (C.13.2)
AF 7. Samples (C.3)
8. Triangulation magnitude and direction
9. Polyline (<∗.pli>-file, C.2)
11. NetCDF grid data (e.g. meteo fields)
14. NetCDF wave data
method integer Method of interpolation:
1. Pass through (no interpolation)
2. Interpolate time and space
3. Interpolate time and space,
save weights (+ optional extrapo-
lation)
DR

4. Interpolate space
5. Interpolate time
7. Interpolate/Extrapolate time
extrapolation_method∗ integer Optionally allow nearest neighbour ex-
trapolation in space (0: no, 1: yes). De-
fault off.
maxsearchradius∗ float Max search radius for nearest neighbor
extrapolation in space.
operand character Overwriting or superimposing values al-
ready set for this quantity:
’O’ Values are overwritten.
’+’ New value is superimposed.
value∗ float custom coefficients for transformation
∗
factor float
∗
ifrctyp float
∗
averagingtype float
relativesearchcellsize∗ float
∗
extrapoltol float
∗
area float Area for source/sink

Note: Keywords marked with ∗ are optional

Remark:
⋄ A polyline file specified as FILENAME for a boundary should only contain a single

Deltares 409 of 562

 Attribute files

polyline. If you need boundaries that consist of multiple unconnected polylines, provide
a separate block for each of them.

C.6.2 New style external forcing

The name of this file is specified using the keyword ExtForceFileNew in the MDU-file (see
Appendix A). External forcings are specified in the ini-file format. Table C.4 lists the structure
of this file.

Table C.4: Definition of external forcings.

T
Keyword Type Default Description
[General]
fileVersion String 2.02 File version. Do not edit this.
AF fileType
[Boundary] definition(s)
[Lateral] definition(s)
extForce File type. Do not edit this.
See Section C.6.2.1.
See Section C.6.2.2.
[Meteo] definition(s) See Section C.6.2.3.
[SourceSink] definition(s) See Section C.6.2.4.

This file may contain one or more [Boundary] and [Lateral]nd [SourceSink] and
[Meteo] blocks, each followed by a set of keywords that specify the location and forcing for
DR

that forcing. See the following sections for details.

Example:

[General]
fileVersion = 2.02
fileType = extForce

[Boundary]
quantity = waterlevelbnd
locationFile = tfl_01.pli
forcingFile = tfl_01.bc

[Lateral]
id = Lateral1
name = First Lateral
type = discharge
locationType = 1d
branchId = Channel1
chainage = 250.000
discharge = 27.3

[Meteo]
quantity = rainfall
forcingFile = precip.nc
forcingFileType = netcdf
targetMaskFile = roofs.pol
targetMaskInvert = true
interpolationMethod = nearestNb

[SourceSink]
id = Id01
locationFile = sourcesink01.pliz
discharge = discharge01.bc

Deltares 410 of 562

 Attribute files

C.6.2.1 Boundary definitions

Table C.5: Boundary definitions in new style external forcing file.

Keyword Type Default Description

(Part of new-style external forcings file, see Table C.5.)
[Boundary] Repeat as needed
quantity String Name of the quantity, see the list in Sec-
tion C.6.3 (boundaries only)

T
locationFile String Name of boundary polyline <∗.pli>.
forcingFile String Name of file containing the forcing for this
boundary. The file may either be a <bc>
file (see section C.5) or a netCDF-file (see
section E.2.4).
AF returnTime
(return_time
earlier versions)
in
Double 0 (Optional) Thatcher-Harleman return time
[s]. See also section 4.3.4. The de-
fault value of 0 seconds means that the
Thatcher-Harleman return time has no im-
pact.
tracerFallVelocity Double 0 (Optional) Fall velocity for this tracer [m/s].
The default value 0 means that settling is
disabled for this tracer.
tracerDecayTime Double 0 (Optional) 1e decay time τ for this tracer,
DR

for a decay to approximately 36.8% [s].

The default value 0 means that tracer de-
cay is disabled for this tracer.

Remarks:
⋄ The tracerfallVelocity is set per tracer, not per boundary location. Multiple
boundaries for the same tracer should not specify different values, otherwise the first
value is used. It is sufficient to set the tracerFallVelocity only once.
⋄ The tracerDecayTime is also set per tracer and follows the same rules as in the
previous remark.
⋄ A polyline file specified as locationFile for a boundary should only contain a single
polyline. If you need boundaries that consist of multiple unconnected polylines, provide
a separate [Boundary]+locationFile for each of them.
⋄ When multiple [Boundary] blocks are present with the same quantity name, the
behavior depends on the locationFile name:
⋄ When also the locationFile full paths are the same, the boundaries are applied
in the order in which they appear in the file, and are added on top of each other
(comparable to implicitly setting OPERAND=+ if this had been an old format external
forcings file, see Section C.6).
⋄ When the locationFile full paths are different, the boundaries are applied in
the order in which they appear in the file, and are overwriting each other (compara-
ble to implicitly setting OPERAND=O if this had been an old format external forcings
file, see Section C.6).
⋄ When using <*.bc files> the quantity names to be used in those files are described
in Section C.5.3.

Deltares 411 of 562

 Attribute files

C.6.2.2 Lateral discharge definitions

Table C.6: Lateral discharge definitions in new style external forcing file.

Keyword Type Default Description

(Part of new-style external forcings file, see Table C.4.)
[Lateral] Repeat as needed
id String Unique lateral discharge id.
name String Long name in the user interface.

T
type String all Deprecated. Replaced by locationType.
locationType String all (optional) Only when xCoordinates and
yCoordinates are also specified. Possible
values are:
AF ⋄ 1d: only affect enclosed 1D grid points
(only valid value when nodeId is given or
branchId and chainage are given).
⋄ 2d: only affect enclosed 2D grid points.
⋄ all: affect all enclosed grid points.
applyTransport Int 0 Defines the way the concentrations of constituents
at lateral locations are taken into account.
⋄ 0 Only water (so without transport of con-
stituents) is added to or removed from the
model, depending on the sign of lateral dis-
DR

charge. For 3D models, lateral discharge is ap-

plied to the top layer of the model.
⋄ 1 Transport of constituent is included. This op-
tion works only in combination with an external
library via BMI-Interface. In a dimr configura-
tion file, users can specify any constituents and
layers of the lateral discharge. If the sign is pos-
itive, lateral discharge is passed to the model
with a concentration set via the BMI-interface.
When negative, discharge is passed from the
model with a concentration equal to that of the
ambient water in the model.
nodeId String (optional) Node id of a 1D network node. The lateral
will be connected to the grid point on/closest to that
network node.
branchId String (optional) For a 1D point lateral: branch on which
the lateral discharge is located, in combination with
chainage.
chainage Double (optional) For a 1D point lateral: location on the
branch of the point-lateral discharge [m], in com-
bination with branchId.
numCoordinates Int (optional) number of values in xCoordinates
and yCoordinates. This value should be ≥ 1.
(continued on next page)

Deltares 412 of 562

 Attribute files

Keyword Type Default Description

(continued from previous page)
xCoordinates Double[] (optional) x-coordinates of the lateral discharge
location polygon [m]. (number of values =
numCoordinates).
yCoordinates Double[] (optional) y-coordinates of the lateral discharge
location polygon [m]. (number of values =
numCoordinates).

T
locationFile String (optional) Name of lateral polygon <∗.pol>.
discharge * The prescribed discharge for this lateral [m3 /s].

Remarks:
AF ⋄ Three types of location specifications are available:
⋄ When nodeId is given, it will be used to snap the lateral to the grid point closest to
that network node (only for 1D).
⋄ When branchId and chainage are given, they will be used for the location
specification (only for 1D).
⋄ When numCoordinates, xCoordinates and yCoordinates are given, or
when locationFile is given, the points will be used to define a polygon. When
numCoordinates ≥ 3, the lateral discharge will be distributed over all grid points
inside that polygon. When instead the number of polygon points = 1, only the 2D
grid cell encompassing that single point will receive the full lateral discharge.
DR

⋄ Items marked with (*) can either be a scalar value, or a time series file (<*.tim>
(deprecated)/<*.bc>) or realtime, to indicate that this parameter gets it values sup-
plied by, e.g., realtime control.
⋄ When using <*.bc files> the quantity names to be used in those files are described in
Section C.5.3.

C.6.2.3 Meteorological forcings

Table C.7: Meteorological forcings in new style external forcing file.

Keyword Type Default Description

(Part of new-style external forcings file, see Table C.4.)
[Meteo] Repeat as needed
quantity String Name of the quantity, see the list in Section C.6.3
(meteo only).
forcingFile String Name of file containing the forcing for this meteo
quantity.
(continued on next page)

Deltares 413 of 562

 Attribute files

Keyword Type Default Description

(continued from previous page)
forcingFileType String Type of forcingFile. Supported types:
⋄ bcAscii: Space-uniform time series in
<*.bc> (Section C.5).
⋄ uniform: Deprecated: Space-uniform time
series in <*.tim> (Section C.4). Use bcAscii
instead.
⋄ netcdf: NetCDF, either with gridded data, or

T
multiple station time series (Section E.2.4).
⋄ uniMagDir: Space-uniform timeseries of vec-
tor data in <*.tim> (Section C.4). Time, magni-
tude and direction in three columns.
⋄ ArcInfo: Time- and space-varying scalar
AF data in a variant of gridded ARCINFO
ASCII <*.amu/amv/amp/amr> (More info
in: (Deltares, 2025k, Section B.7.1)).
⋄ curviGrid: Time- and space-varying scalar
data in defined on a separate curvilinear grid
in <*.amu/amv/amp/amr> or <*.apwxwy>
(More info in: (Deltares, 2025k, Section B.7.2)).
⋄ spiderWeb: Time- and space-varying wind
and pressure on a spiderweb grid <*.spw>
(More info in: (Deltares, 2025k, Section B.7.3)).
DR

forcingVariableName String (Optional) name of data variable in the forcing file,

typically used with NetCDF files.
locationType String Obsolete! Maybe needed in the future for multi-
station data in bcAscii files.
targetMaskFile String (optional) Name of <*.pol> file to be used as mask.
Grid parts inside any polygon will receive the meteo
forcing.
targetMaskInvert Logical no (optional) Flag indicating whether the target mask
should be inverted, i.e., outside of all polygons: no
or yes.
interpolationMethod String Type of (spatial) interpolation. Supported methods:
⋄ linearSpaceTime: linear interpolation, both
in space and time.
⋄ nearestNb: nearest neighbor in space
(linear in time), only with station data in
forcingFileType=netcdf.
extrapolation ←- Logical no Note: this setting is subject to future change. Op-
Allowed tion for (spatial) extrapolation: no or yes. Used
to fill holes in input forcing data, but not beyond
the bounding box of that input forcing data. Uses
nearest-neighbour extrapolation. Only available for
forcingFileType=netcdf.
(continued on next page)

Deltares 414 of 562

 Attribute files

Keyword Type Default Description

(continued from previous page)
operand String O (optional) How this data is combined with previ-
ous data for the same quantity (if any). Supported
operands:
⋄ O, override any previous data.
⋄ V, override any previous data only
where the provided forcing data file con-
tains actual values. Only available for

T
forcingFileType=netcdf.
⋄ +, adds the provided values to the existing val-
AF ues.

Remarks:
⋄ Spatially uniform meteo forcing is available as forcingFileType=bcAscii, when
that file contains a scalar time series in a block with name=global.
⋄ Multiple station time series is available as forcingFileType=netcdf, when that
file contains a time series variable with a station dimension. The station feature is
identified via the attribute :cf_role="timeseries_id". x- and y -coordinates
must also be present, to support spatial interpolation.

C.6.2.4 Source and sink definitions

DR

Table C.8: Source and sink definitions in new style external forcing file.

Keyword Type Default Description

(Part of new-style external forcings file, see Table C.4.)
[SourceSink] Repeat as needed
id String Unique id.
name String Long name in the user interface.
locationFile String (optional) Name of source sink polyline <∗.pli> or
<∗.pliz>.
numCoordinates Int (optional) Number of values in xCoordinates
and yCoordinates. This value should be ≥ 1.
xCoordinates Double[] (optional) x-coordinates of the source/sink dis-
charge location polygon [m] (number of values =
numCoordinates).
yCoordinates Double[] (optional) y-coordinates of the source/sink dis-
charge location polygon [m] (number of values =
numCoordinates).
zSource Double[] (optional) 1 (or 2) value(s) to specify in which verti-
cal layer (range) the source is located (see section
7.4.11).
zSink Double[] (optional) 1 (or 2) value(s) to specify in which ver-
tical layer (range) the sink is located (see section
7.4.11).
(continued on next page)

Deltares 415 of 562

 Attribute files

Keyword Type Default Description

(continued from previous page)
discharge * The prescribed discharge for the source [m3 /s].
area Double (optional) If present: used to compute the momen-
tum released at the source location (see section
7.4.11).
salinityDelta * (optional) The prescribed salinity difference be-
tween source and sink.

T
temperatureDelta * (optional) The prescribed temperature difference
between source and sink.
sedFrac<fractionname>Delta
* (optional) The prescribed difference in concentra-
AF tracer<tracername>Delta
tion for sediment <fractionname> between source
and sink.

* (optional) The prescribed difference in concentra-

tion for tracer <tracername> between source and
sink.

Remarks:
⋄ Items marked with (*) can either be a scalar value (Double), or the name of a time series
DR

file <*.bc> (String) or realtime, to indicate that this parameter gets it values sup-
plied by, e.g., realtime control. Keyword realtime is not (yet) available for sediment
fractions and tracers.
⋄ When using <*.bc files> the quantity names to be used in those files are described in
Section C.5.3.
⋄ Names of sediment fractions and tracers may contain special characters. For the key-
words above, it is expected that spaces and forward slashes are replaced by under-
scores.

C.6.3 Accepted quantity names

The list of accepted quantity names is subdivided into six categories:
⋄ Boundary conditions (old and new <*.ext> file)
⋄ Meteorological fields (old and new <*.ext> file)
⋄ Structure parameters (old <*.ext> file and Structure INI file)
⋄ Initial fields (old <*.ext> file and initial field/parameter file)
⋄ Spatial physical properties (old <*.ext> file and initial field/parameter file)
⋄ Miscellaneous (mainly old <*.ext> file)

Table C.9: List of accepted external forcing quantity names.

Quantity pg. Description

Boundary conditions: (old and new ext)
waterlevelbnd 160 Water level
neumannbnd 162 Water level gradient

Deltares 416 of 562

 Attribute files

Quantity pg. Description

riemannbnd 163 Riemann invariant

outflowbnd
velocitybnd 161 Velocity
dischargebnd 160 Discharge
riemann_velocitybnd Riemann invariant velocity
salinitybnd 37 Salinity

T
temperaturebnd 37 Temperature
sedfracbnd<fractionname> see1 Suspended sediment concentration for frac-
tion <fractionname>
uxuyadvectionvelocitybnd
normalvelocitybnd, 169 Normal and tangential velocity (only in 2D)
AF
tangentialvelocitybnd
qhbnd
tracerbnd<tracername>
164
37
Discharge-water level dependency
User-defined tracer
absgenbnd Absorbing-generating boundary

Meteorological fields: (Items marked with †

are deprecated, available in old ext file only)
windx, windy, windxy 226 Wind components, wind vector
†
windspeedfactor Dimensionless coefficient to downscale wind
speeds (e.g. near wind farms).
DR

windstresscoefficient† Spatially varying wind drag coefficient Cd ,

constant for all wind speeds. Not yet in new
<*.ext> file, currently available via initial fields
and parameters file.
airpressure, charnock
airpressure_windx_windy 226 Atmospheric pressure and wind components
airpressure_windx_windy_charnock
atmosphericpressure 226 Atmospheric pressure
rainfall or rainfall_rate 230 Precipitation
humidity, cloudiness
airdensity, airpressure, 218 Varying air density
airtemperature, dewpoint
humidity_airtemperature... 467 Combined heat flux terms
..._cloudiness
humidity_airtemperature...
..._cloudiness_solarradiation
dewpoint_airtemperature...
..._cloudiness
dewpoint_airtemperature...
..._cloudiness_solarradiation
longwaveradiation 467 Long wave radiation
solarradiation 467 Solar radiation
†
solarradiationfactor 467 Solar radiation factor

1
Deltares (2025d)

Deltares 417 of 562

 Attribute files

Quantity pg. Description

Sources and sinks: In new <*.ext> file, use specific keyword to

supply forcing for each quantity (See Sec-
tion C.6.2.4).
discharge_salinity... 36 Discharge, salinity and heat sources
..._temperature_sorsin†

T
Structure parameters: (old ext only) Deprecated, use preferred structure INI file in-
stead (See Section C.12).
pump 202 via type=pump, capacity=...
damlevel via type=weir, crestLevel=...
gateloweredgelevel via type=gate,
AF
generalstructure
gateLowerEdgeLevel=...
via type=generalStructure,
crestLevel=..., etc.

Initial fields: (old ext only)

initialwaterlevel 462
initialsalinity 462
initialsalinitytop 462
initialtemperature 463
DR

initialverticaltemperatureprofile463
initialverticalsalinityprofile 462
initialtracer<tracername> 463
initialsedfrac<fractionname> see1 Initial suspended sediment concentration for
fraction <fractionname>

Spatial physical properties: (old ext only) 463

frictioncoefficient
horizontaleddyviscositycoefficient
horizontaleddydiffusivitycoefficient
advectiontype
ibotlevtype

Water quality processes: 267

waqparameter 273 Processes input that varies in space
waqfunction 274 Processes input that varies in time
waqsegmentfunction 274 Processes input that varies in time
waqmassbalancearea 279 Definition of mass balance area
waqparameterProcessesInactive 278 Area where processes are switch off
waqsegmentnumber 278 Global segmentnumbers for D-Water Quality
processes
Miscellaneous:
shiptxy
movingstationxy 476 Moving observation point for output (time,x,y)

Deltares 418 of 562

 Attribute files

Quantity pg. Description

wavesignificantheight 257 Wave related input

waveperiod 257 Wave related input

C.6.4 Overview of deprecated and removed keywords

The following table lists in alphabetical order per data block the deprecated keywords (which are cur-
rently still supported by D-Flow FM, but may be removed in a future release) and the removed keywords

T
(which are no longer processed). When the functionality of the keyword has is now supported via an-
other keyword then the new keyword is specified.

Table C.10: Deprecated and obsolete keywords in external forcings file.

Keyword Action
AF [Lateral]
flow
type
Replace with keyword discharge.
Either remove or replace with keyword locationType.
[Meteo]
locationFile Replace with keyword targetMaskFile.

C.7 Trachytopes
The trachytope functionality allows for the usage of different types of roughness formulations at different
locations within the computational domain. Multiple formulation may be active in the same grid cell.
DR

Several keywords in the MDU file influence the functioning. All keywords below should be placed
underneath the [trachytopes] section in the MDU file.

Deltares 419 of 562

 Attribute files

Keyword Value Description Default

TrtRou Y or N Trachytope option activated N

TrtDef <name.ttd> Definition file trachytopes

Trtl <name.arl> Area Roughness on Link file trachy-

topes
DtTrt pos. real Time step in seconds for updat- 1 DtUser
ing roughness and resistance coef-

T
ficients based on trachytopes. Must
be a multiple of DtUser.
Make #name# Spatial calibration factor for trachy- uniform 1
spatially topes
varying
input
AF calibration
possible
TrtCll
TrtMnH pos. real Minimum water depth in roughness .2 Epshu
computation
TrtMth 1 or 2 Area averaging method 1

TrtAsr real ∈ [0, 1] Serial factor in averaging of area 0.6

roughnesses
TrtMxR integer Maximum recursion depth for mixed 8
DR

trachytope definitions

Limitation: DtTrt must be a multiple of DtUser

C.7.1 Area Roughness on Links (ARL-file)

File contents The Area Roughness on Links file (ARL-file) is the input file for the spatial
distribution of the alluvial and vegetation roughness which are handled by
the trachytopes module.
Filetype ASCII
File format Space separated file format
Filename <name.arl>
Generated At present: Conversion possible from structured grid Delft3D-FLOW in-
put files with matlab conversion tool from Open Earth Tools (http://www.
openearth.info/), see example below ( section C.7.1.2).

The ARL file has the following properties:

⋄ A single line comment, starts with a hash “#” or an asterisk “*”.
⋄ Each line has the format
“xu yu zu TrachytopesNr Fraction”,
where xu, yu, zu is the coordinate of the midpoint of the netlink,
⋄ ⋄

TrachytopeNr is an integer corresponding to the number as described in the TrachyTopes

Definition File (cf. section C.7.2),
and the meaning of Fraction depends on the TrachytopeNr (see below).
⋄

⋄ A combination of multiple trachytopes can be applied by specifying multiple consecutive lines with
the same set of midpoint-netlink-coordinates xu, yu, zu (ignoring any comment lines). If lines for
the same set of coordinates xu, yu, zu are not consecutive, then the last (set of consecutive)
line(s) will overrule all earlier lines.
⋄ If the TrachytopeNr refers to an area trachytope, then the Fraction represents the fraction
of the momentum control volume associated with that trachytope. This fractions should be between

Deltares 420 of 562

 Attribute files

0.0 and 1.0. The sum of the Fraction values of all area trachytopes associated with one link,
should sum to a value of at most 1.0. If the sum is less than 1.0 the background roughness
prescribed in the [physics] chapter in the MDU file is prescribed for the remaining Fraction,
cf. Appendix A. Only a single roughness type is allowed in combination with the Trachytopes
module.
⋄ If the TrachytopeNr refers to a linear trachytope, then the Fraction represents the length of
the linear roughness element projected onto the netlink, relative to the length of the netlink (flow
width). This value should be 0.0 or larger. The total projected length of multiple lines, e.g. multiple
rows of hedges, may sum to a value larger than 1.0.
⋄ If the TrachytopeNr refers to a point trachytope, then the Fraction refers to the product of
n, the number of trees per unit area, and D, the characteristic tree diameter. This value should be

T
0.0 or larger, but significantly smaller than 1/D.

C.7.1.1 Example
An example of the <arl> file is given below based on the <ttd> file given in section C.7.2. In this case
the netlink with u point located at xu = 10.542 and yu = 11.6, which is covered for 30 %, 30 % 20 %
AF and 20 % for TrachytopeNr = 1, 2, 4 and 3 respectively.

(continued)
...
10.542 11.6 0 1 0.3
10.542 11.6 0 2 0.3
10.542 11.6 0 4 0.2
10.542 11.6 0 3 0.2
...
(continued)
DR
C.7.1.2 Conversion from Delft3D 4 input files
Open Earth Tools has different matlab tools available for the conversion of Delft3D-FLOW models to
D-Flow FM models (e.g. dflowfmConverter.m and d3d2dflowfm.m).

An extra Matlab conversion script has been added to convert Delft3D-FLOW’s <∗.aru> and <∗.arv>
files to <∗.arl> files for D-Flow FM:
d3d2dflowfm_friction_trachytopes.m.

It can be called as follows:

oetsettings
d3d2dflowfm_friction_trachytopes(filgrd,filaru,filarv,filnet,filarl)

where the variables are defined as follows:

filgrd Delft3D-FLOW grid filename (*.grd)
filaru Delft3D-FLOW area definition file in u-direction (*.aru)
filarv Delft3D-FLOW area definition file in v-direction (*.arv)
filnet name of the dflowfm network file (*_net.nc)
filarl name of the dflowfm trachytope file (*.arl))

C.7.2 Trachytope Definition file (TTD-file)

The trachytope definition file contains lines of the following format defining the different types of trachy-
topes. The types which are supported are general, discharge dependent and water-level dependent
formats.

C.7.2.1 General format

The general format is formatted as follows:

Deltares 421 of 562

 Attribute files

TrachytopeNr FormulaNr ...Parameters...

where ...Parameters... indicates a space separated list of formula specific parameters; the
parameters required and their order are specified in section C.7.2.5. The user must specify for each
trachytope (combination of formula number and parameters) a unique positive trachytope number. This
trachytope number is used in the area files (see section C.7.1) to indicate the roughness types on a
net link.

C.7.2.2 Example

T
An example of such a file where the first three codes 1–3 with a Nikuradse roughness height are
defined, and the fourth (code 4) is Chézy roughness height.

1 51 0.1
2 51 0.2
3 51 0.3
AF
C.7.2.3
4 52 35

Discharge dependent format

The discharge dependent format is formatted as follows:

TrachytopeNr DISCHARGE "Cross-section name"

TrachytopeNr Q1 FormulaNr ...Parameters...
TrachytopeNr Q2 FormulaNr ...Parameters...
TrachytopeNr Q3 FormulaNr ...Parameters...
TrachytopeNr Q4 FormulaNr ...Parameters...
...
DR

which again expects a user defined TrachytopeNr. The first row contains the keyword “DIS-
CHARGE” and subsequently a cross-section name occuring in CrsFile in the mdu-file.

The cross-section name can be enclosed by quotation marks, for instance when the cross-section
name is made up of more than one word. The subsequent rows all have the same TrachytopeNr
as the first row and furthermore every FormulaNr should be the same. The list of discharges Q1,
Q2, Q3, Q4 should be monotonically increasing.

The ...Parameters... for each formula type are specified in section C.7.2.5.

C.7.2.4 Water level dependent format

The water-level dependent format is similar to the discharge dependent format and is formatted as
follows:

TrachytopeNr WATERLEVEL "Observation-station name"

TrachytopeNr ZS1 FormulaNr ...Parameters...
TrachytopeNr ZS2 FormulaNr ...Parameters...
TrachytopeNr ZS3 FormulaNr ...Parameters...
TrachytopeNr ZS4 FormulaNr ...Parameters...
...

which again expects a user defined TrachytopeNr. The first row contains the keyword “WA-
TERLEVEL” and subsequently an observation-station name occuring in ObsFile in the mdu-file. The
observation-statopm name can be enclosed by quotation marks, for instance when the observation-
station name is made up of more than one word. The subsequent rows all have the same TrachytopeNr
as the first row and furthermore every FormulaNr should be the same. The list of waterlevels ZS1,
ZS2, ZS3, ZS4 should be monotonically increasing.

The ...Parameters... for each formula type are specified in section C.7.2.5.

Deltares 422 of 562

 Attribute files

C.7.2.5 Supported roughness formulations

The roughness formulations specified in the table below are supported by D-Flow FM. These formula-
tions are specified in the .ttd by FormulaNr and ...Parameters... in the order in which they
appear in the table below. The related formulae are presented in the Technical Reference Manual

FormulaNr Description Parameters

Special classes (1–50)

1 flood protected area, reduces the effective area –

T
of the grid cell. It has no influence on the continu-
ity equation (i.e. it does not decrease the surface
area of the grid cell).

2 composite trachytope: fraction α of type T1 and T1 , T2 , α, β

fraction β (generally β = 1 − α) of type T2
AF Area trachytope classes: simple type (51–100)

51 constant White-Colebrook/Nikuradse value k [m]

52 constant Chézy value C [m1/2 /s]
53 constant Manning value n [s/m1/3 ]
54 constant z0 value z0 [m]

61 constant White-Colebrook/Nikuradse values for kebb [m], kf lood [m]

ebb and flood
62 constant Chézy values for ebb and flood Cebb [m1/2 /s], Cf lood [m1/2 /s]
DR

63 constant Manning values for ebb and flood nebb [s/m1/3 ], nf lood [s/m1/3 ]
64 constant z0 values for ebb and flood z0,ebb [m], z0,f lood [m]

Area trachytope classes: alluvial type (101–150)

101 simplified Van Rijn A [m0.3 ], B [m0.3 ]

102 power relation A [m1/2 /s], B [-]
2
103 Van Rijn predictor -
104 2
Struiksma predictor A1 [m1/2 /s], A2 [-], θc [-], θm
[-], Cmin [m1/2 /s]
1052 bedforms quadratic -
1062 bedforms linear -

Area trachytope classes: vegetation type (151–200)

151 Barneveld 1 hv [m], n [1/m]

152 Barneveld 2 hv [m], n [1/m], CD [-], kb [m]
153 Baptist 1 hv [m], n [1/m], CD [-], Cb
[m1/2 /s]
154 Baptist 2 hv [m], n [1/m], CD [-], Cb
[m1/2 /s]

2
Formulae 103, 104, 105 and 106 use the D50 and D90 data from the sediment transport and morphology
module if available. In case of a simulation without sediment, these values are obtained from the keywords
BdfD50 and optionally BdfD90 in the [bedform] of the mdu-file. The values of BdfD50 and BdfD90 are a
constant value for the whole grid, or the file name of a file containing a spatial varying field. The default value for
D50 is 0.2 mm, and the default value for D90 is 1.5D50 .

Deltares 423 of 562

 Attribute files

FormulaNr Description Parameters

Linear trachytope classes: various (201–250)

201 hedges 1 hv [m], n [1/m]

202 hedges 2 hv [m], n [1/m]

Linear trachytope classes: various (251–300)

251 trees hv [-], CD [-]

T
C.8 Fixed weirs
A fixed weir has many quantitites. On a polyline several quantitites has to be specified. In the table
AF below an overview is given of all these quantities.

Keyword Description Default value

X-coordinate X-coordinate of polyline point -

y-coordinate Y-coordinate of polyline point -

Crest level Absolute crest level - [mAD]

Ground height left Difference between crest level 0.0 [m]

and toe level at left side
DR

Ground height right Difference between crest level 0.0 [m]

and toe level at right side
Crest width Width of weir in perpendicular di- 3.0 [m]
rection
Slope left Slope of weir at left side 4.0 [-]

Slope right Slope of weir at right side 4.0 [-]

Roughness code Roughness code for vegetation 0.0 [-]

on weir
Weir type (v)illemonte or (t)abellenboek v [-]

in which ’mAD’ stands for ’meter Above Datum’, which denotes a level relative to the vertical reference
system. The last column with the weir type (Villemonte or Tabellenboek) is optional. In this way,
individual polyline can be given another weir type. For example, if FixedweirType=9 (Villemonte) has
been specified in the MDU-file, then individual polylines can be set to Tabellenboek by adding a "t" to
all points in the polyline; see the example below.

The default value for the ground height levels (left and right) is 0.0 m. However, in case of the Tabellen-
boek a minimum value for the ground heights of 0.1 m is applied, because the empirical Tabellenboek
relation doesn’t allow values smaller than 0.1 m. Noted that in WAQUA also a minimum value of 0.1
m is applied in case of the Tabellenboek. For fixed weirs also a shape file can be generated, see
section 7.4.14. In case of the Tabellenboek the ground heights in the shape file can be slightly different
from the value in the input file, because a minimum value of 0.1 m is applied.

For some of the fixed weir input quantities upper and lower limits are applied, because realistic input
values are required for an accurate computation of the energy losses of fixed weirs. This involves a
maximum crest level of 10000 [m], a minimum slope of 0.0000001 [-], a maximum slope of 1000 [-],

Deltares 424 of 562

 Attribute files

a minimum ground height of 0.0 [m] and a maximum ground height of 500 [m]. If one of these values
isn’t between the lower and upper limit, then an error message is written to the diagnostic file and the
simulation will stop. Then, the user has to check the fixed weirs input file for erroneous values. Below
an example is given of an error message for fixed weirs in the diagnostic file, in which a negative slope
is applied.

** INFO : Opened file : harlingen-1_fxw_error.pliz

** INFO : Closed file : harlingen-1_fxw_error.pliz
** WARNING: Slope left -0.10000D+01 is smaller than the minimum limit 0.10000D-07.
** WARNING: Slope left is located at line 2 in PLI FixedWeir01 of file harlingen-1_fxw_error.pliz.
** ERROR : Some fixed weirs have values outside of limits. See messages above.

T
Example
AF An example of a polyline with fixed weir input is given below. It consists of a polyline with two points

(continued)
...
weir
2 10
399.999420 99.997688 2.0 0.2 0.8 3.0 4.0 4.0 0 t
399.999420 100.999542 2.1 0.3 0.9 3.0 4.0 4.0 0 t

...
(continued)

In general, fixed weir polylines do not coincide with the computational grid. The polylines are snapped
to flow links, which is illustrated in Figure 7.15. This is computed by the computational kernel of D-
DR

Flow FM.

In practice, it is possible that a certain flow link contains multiple snapped fixed weirs. This is for
example the case when polylines with fixed weirs cross each other. Then, the fixed weir with the
highest crest level is taken, because the crest level is used in the drying-flooding algorithm. In this way,
overtopping of a weir the water level only occurs if the water level is above the weir with the highest
crest level.

C.9 Calibration Factors

The calibration factor functionality is a multiplier for the rouhgness at different locations within the com-
putational domain. Multiple formulation may be active in the same grid cell. Several keywords in the
MDU file influence the functioning. All keywords below should be placed under the [calibration]
section in the MDU file.

Keyword Value Description Default

UseCalibration 1 or 0 Calibration factor option activated N

DefinitionFile<name.cld> Calibration factor definition file

AreaFile <name.cll> Calibration factor area file

C.9.1 Calibration factor definition file (CLD-file)

The calibration class definition file contains lines of the following format defining the different calibration
classes. It supports constant values and values that depend on the discharge at a named cross section
or the water level at a named location.

Deltares 425 of 562

 Attribute files

C.9.1.1 Header of the CLD-file

The file starts with the following header

# [FileInformation]
# FileType = CalibrationFactorsDefinitionFile
# FileVersion = 1.0
# [CalibrationFactors]

C.9.1.2 Constant values

T
The format for constant values is as follows:

CalibrationClassNr ConstantValue
AF where ConstantValue indicates the calibration value to be used (use 1.0 to use the uncalibrated
roughness). The user must specify for each calibration class (line in this file) a unique calibration class
number CalibrationClassNr. This calibration class number is used in the calibration area <.cll>
file to indicate the area of influence of this class.

C.9.1.3 Discharge dependent format

The discharge dependent line is formatted as follows:

CalibrationClassNr DISCHARGE "Cross-section name"

DR

CalibrationClassNr Q1 ConstantValueAtQ1
CalibrationClassNr Q2 ConstantValueAtQ2
CalibrationClassNr Q3 ConstantValueAtQ3
CalibrationClassNr Q4 ConstantValueAtQ4
...

which again expects a user defined calibration class number CalibrationClassNr. The first line
contains the keyword DISCHARGE and subsequently a cross-section name occurring in the CrsFile in
the mdu-file. The cross-section name can be enclosed by quotation marks, for instance when the name
contains spaces. The subsequent lines all start with the same calibration class number as the first line.
The list of discharges Q1, Q2, Q3, and Q4 should be monotonically increasing. For each discharge
value a calibration value should be specified. Between the discharges specified, the calibration values
are linearly interpolated. Below the minimum and above the maximum discharge the first and last
values are used respectively.

C.9.1.4 Water level dependent format

The water-level dependent format is similar to the discharge dependent format and is formatted as
follows:

CalibrationClassNr WATERLEVEL "Observation-station name"

CalibrationClassNr ZS1 ConstantValueAtZS1
CalibrationClassNr ZS2 ConstantValueAtZS2
CalibrationClassNr ZS3 ConstantValueAtZS3
CalibrationClassNr ZS4 ConstantValueAtZS4
...

which again expects a user defined calibration class number CalibrationClassNr. The first
line contains the keyword WATERLEVEL and subsequently an observation-station name occurring

Deltares 426 of 562

 Attribute files

in ObsFile in the mdu-file. The observation-station name can be enclosed by quotation marks, for
instance when the name contains spaces. The subsequent lines all start with the same calibration
class number as the first line. The list of water levels ZS1, ZS2, ZS3, and ZS4 should be monotonically
increasing. For each water level value a calibration value should be specified. Between the water levels
specified, the calibration values are linearly interpolated. Below the minimum and above the maximum
water level the first and last values are used respectively.

C.9.1.5 Example
The example file given below defines three calibration classes. In the area associated with the first
class, the roughness values are used without any adjustment. In the area associated with the second

T
class, the roughness value is decreased by 20%. In the area associated with the third and final class,
the increase in the roughness value varies between 0% and 30% depending on the discharge at a
specific location.

# [FileInformation]
AF #
#
FileType = CalibrationFactorsDefinitionFile
FileVersion = 1.0
# [CalibrationFactors]

# areas without any calibration adjustment

1 1.0

# areas with 20% decreased roughness value

2 0.8

# area with calibration depending on discharge at crsX

DR

10 DISCHARGE 'crsX'
10 500 1.0
10 1000 1.1
10 3000 1.3

C.9.2 Calibration Class Area on Links (CLL-file)

C.9.2.1 Header of the CLL-file

The file starts with the following header

# [FileInformation]
# FileType = CalibrationAreasFile
# FileVersion = 1.0
# [CalibrationAreas]

C.9.2.2 Body of the CLL-file

The body of the CLL-file consists of comment lines (any line starting with # or *) or data lines of the
following format:

xu yu zu CalibrationClassNr AreaFraction

where xu, yu, zu is the coordinate of the midpoint of the netlink, CalibrationClassNr is an inte-
ger corresponding to the number as described in the Calibration Class Definition File (cf. section C.9.1),
and AreaFraction is an area fraction between 0.0 and 1.0.

All lines that list the same xu, yu, zu coordinates are combined to a weighted average of multiple
calibration classes, provided the sum of the fractions does not add to a value greater than 1.0.

Deltares 427 of 562

 Attribute files

If the sum of the areas specified for a certain netlink is less than 1.0, then the a constant calibration
factor of 1.0 is assumed for the remaining area (i.e. no calibration effect). The result is that if for a
specific netlink no line is specified at all, then the roughness of this netlink will be unaffected by the
calibration process.

C.9.2.3 Example
The example of the <CLL>-file is given below based on the <CLD>-file given in section C.9.1. In
this case the roughness at netlink with midpoint located at xu = 10.542 and yu = 11.6 is completely
affected by calibration class 1, the netlink with midpoint at xu = 11.120 and yu = 12.1 is affected for
60 % by calibration class 1 and 40 % by calibration class 10, and the final location listed uses only the

T
value resulting from calibration class 10.

...
10.542 11.6 0 1 1.0
AF 11.120
11.120
12.635
...
12.1
12.1
12.6
0
0
0
1 0.6
10 0.4
10 1.0

C.10 Sources and sinks

Warning:
⋄ This section describes deprecated functionality using the old external forcings format. Use the
new external forcings file for source sinks instead, see Section C.6.2.4.

Sources and sinks (section 7.4.11) are defined as part of the <∗.ext> file, as follows:
DR

QUANTITY=discharge_salinity_temperature_sorsin
FILENAME=chan1_westeast.pli # A file 'chan1_westeast.tim', with same basename
# as the polyline should be present
FILETYPE=9
METHOD =1
OPERAND =O
AREA =1.5

The <∗.pli(z)> file is a polyline file (section C.2) with two or three or five columns. 2D models only
need two (x, y ) columns. A 3D model with extraction and discharge in a single layer needs three
(x, y, z ) columns. It is also possible to extract and/or discharge into a range of vertical layers. This
must be specified in a five-column file (x, y, zmin , zmax , 0), where the fifth column is a dummy unused
value and zmin , zmax define the range of layers across which the discharge is averaged. Along with
the <∗.pli(z)>-file, there has to be a time series file (section C.4) with the same basename as the
<∗.pli(z)>-file, and extension <.tim>. The columns in the <∗.tim> are as follows: time in minutes,
discharge Q in [m3 /s], and all constituents in the model. The order of consituents is: salinity in [ppt],
temperature T in [◦ C], sediment concentrations, spiral flow intensity and tracers. For example, if we
only have temperature and two tracers we get 5 columns: time, discharge, temperature, tracer 1, tracer
2. For more information, see section 7.4.11.

C.11 Dry points and areas

Dry points can either be defined by a basic sample file (see section C.3), or a polygon file (see sec-
tion C.2).

Special attention must be given to the optional third column of a polygon file: when the first point has
a z -value of −1, the polygon mask is inverted, i.e., all points outside the polygon are set as dry points.

Deltares 428 of 562

 Attribute files

More details can be found in section 7.4.2.7.

C.12 Structure INI file

Hydraulic structures are defined in a <structures.ini> file. Each structure is defined in its own [Structure]
section, followed by a set of key-value parameters that depend on the type of structure:

Table C.12: General part of structure file.

Keyword Type Default Description

T
[General]
fileVersion String 3.01 File version. Do not edit this.

AF fileType String structure File type. Do not edit this.

[Structure]
id String Unique structure id (max. 256 characters).
name String Given name in the user interface.
branchId String (optional) Branch on which the structure is lo-
cated.
chainage Double (optional) Chainage on the branch [m].
numCoordinates int (optional) Number of values in
xCoordinates and yCoordinates.
This value should be greater or equal 2.
xCoordinates Double (optional) x-coordinates of the location
DR

of the structure. (number of values =

numCoordinates)
yCoordinates Double (optional) y-coordinates of the location
of the structure. (number of values =
numCoordinates)
locationFile String Filename of a <*.pli> file containing x-/y-
points of the structure’s position.
type String Structure type. Possible values:
⋄ weir (for specific input refer to C.12.1)
⋄ universalWeir (for specific input refer
to C.12.2)
⋄ culvert (for specific input refer to
C.12.3)
⋄ longCulvert (for specific input refer to
C.12.4)
⋄ bridge (for specific input refer to C.12.6)
⋄ pump (for specific input refer to C.12.7)
⋄ orifice (for specific input refer to
C.12.8)
⋄ gate (for specific input refer to C.12.9)
⋄ generalStructure (for specific input
refer to C.12.10)
⋄ dambreak (for specific input refer to
C.12.11)
⋄ compound (for specific input refer to
C.12.12)
... Structure type specific data

Remarks:

Deltares 429 of 562

 Attribute files

⋄ When branchId and chainage are given, they will be used for the location specification
(only for 1D).
⋄ When numCoordinates, xCoordinates and yCoordinates are given, or when locationFile
is given, the points will be used to define a polyline. All flow links crossing that polyline will fall
under the influence of that hydraulic structure.
⋄ The structure id/name may contain spaces, with no quoting needed.
⋄ All structure types require a location specification as above, except for the compound structure.
The latter should not have a location specification; it is inherited from its underlying structures
(Section C.12.12).
⋄ When direction is of importance (e.g., for structures with an allowedFlowDir, and for all flux
quantities output), the positive direction is oriented as follows:

T
⋄ When placed on 1D branch, in the direction of the branch.
⋄ When placed via a polyline (x/yCoordinates or locationFile), the positive direc-
tion is oriented 90 degrees clockwise w.r.t. the polyline.
⋄ The universal weir, culvert and bridge can only be used in a single 1D channel.
⋄ The long culvert does not follow the location specifications described above. Instead, the poly-
AF line coordinates should lie on top of 1D network nodes, to define the location and length in the
positive flow direction.
⋄ All other structures will be split up over the intersecting flow links.
⋄ When using <*.bc files> to control some structure parameters, the quantity names to be used
in those files are described in Section C.5.3.

C.12.1 Weir
The data block for a weir structure in the <structures.ini> file is described in this section. The geomet-
rical shape and hydraulic treatment is further described in Section 12.4.
DR

Table C.13: Weir definition.

Keyword Type Default Description

[Structure]
type String weir Structure type; must read weir.
allowedFlowdir String both Possible values: both, positive,
negative, none.
crestLevel * Crest level of weir [m AD].
P
crestWidth Double wu Width of weir [m].
corrCoeff Double 1.0 Correction coefficient [-].
useVelocityHeight logical true Flag indicates whether the velocity height is to be
calculated or not.

Remarks:
⋄ Items marked with (*) can either be a scalar value, or a time series file (<*.bc>, see more
details in Section C.12.13/(deprecated) <*.tim>) or realtime, to indicate that this parameter
gets it values supplied by, e.g., realtime control.
⋄ crestWidth is optional. Default is (the sum of) the width[s] of the flow link[s]. If the given
value is larger than this sum, it is automatically lowered to this default.
⋄ If the crestWidth of a 2d structure is smaller than the sum of the widths of the 2d links,
the crestWidth of the individual structure elements is reduced symmetrical from the outside
inwards.

C.12.2 Universal Weir

The data block for a universal weir structure in the <structures.ini> file is described in this section.
The geometrical shape and hydraulic treatment is further described in Section 12.10.

Deltares 430 of 562

 Attribute files

Table C.14: Universal Weir definition.

Keyword Type Default Description

[Structure]
type String universal Structure type; must read universalWeir.
Weir
allowedFlowDir String both Possible values: both, positive,
negative, none.
numLevels Int Number of yz-Values.

T
yValues Double[] y-values of the cross section [m]. (number of val-
ues = numLevels)
zValues Double[] z-values of the cross section [m]. (number of val-
ues = numLevels)
crestLevel Double Crest level of weir [m AD].
AF dischargeCoeff Double Discharge coefficient ce [-], as used in the formu-
las in Section 12.10.

Remark:
⋄ The zValues should be considered as relative values, merely defining the shape of the cross
section. The absolute z-values are determined by shifting the entire cross section such that the
lowest point is exactly at crestLevel.

C.12.3 Culvert
DR

The data block for a culvert structure in the <structures.ini> file is described in this section. The
geometrical shape is described by the parameters in the following table and these refer to the symbols
in Figure 12.8. The entrance and exit losses are further described in Section 12.7.

Table C.15: Culvert

Keyword Type Default Description

[Structure]
type String culvert Structure type; must read culvert.
allowedFlowdir String both Possible values: both, positive,
negative, none.
leftLevel Double Left invert level of the culvert (zc1 ) [m AD].
rightLevel Double Right invert level of the culvert (zc2 ) [m AD].
csDefId String Id of cross section definition.
length Double Length (L) [m].
inletLossCoeff Double Inlet loss coefficient (ξi ) [-].
outletLossCoeff Double Outlet loss coefficient (ξo ) [-].
valveOnOff Int Flag for having valve or not (0=no valve, 1=valve).
valveOpeningHeight Double Valve opening height (hvalve ) [m].

Table for loss coefficients of valve.

numLossCoeff Int Number of rows in table.
relOpening Double[] Relative valve opening (0.0 — 1.0) [-]. (number of
values = numLossCoeff)
(continued on next page)

Deltares 431 of 562

 Attribute files

Keyword Type Default Description

(continued from previous page)
lossCoeff Double[] Loss coefficients (ξv ) [-]. (number of values =
numLossCoeff)
bedFrictionType String Friction type, possible values are listed in ??.
bedFriction Double Friction Value.
subType String culvert Defines the behaviour of the culvert. Possible val-
ues: culvert and invertedSiphon.
bendLossCoeff Double Bend loss coefficient (ξb ) of the inverted siphon.

T
Remarks:
⋄ Items marked with (*) can either be a scalar value, or a time series file (<*.bc>, see more
details in Section C.12.13/(deprecated) <*.tim>) or realtime, to indicate that this parameter
AF gets it values supplied by, e.g., realtime control.
⋄ valveOpeningHeight is a relative height with respect of the invert level of the culvert.
Thus, a positive value should be prescribed. Note that D-Flow FM doesn’t check on negative
values. This may result into a crash of the simulation.
⋄ bendLosses is mandatory in case of an inverted siphon, but is not allowed in combination
with a culvert.

C.12.4 Long culvert

The data block for a long culvert structure in the <structures.ini> file is described in this section. The
geometrical shape is described by the parameters in the following table and these refer to the symbols
in Figure 12.11. The geometrical details are further described in Section 12.8.1.
DR

Table C.16: Long culvert

Keyword Type Default Description

[Structure]
type String longCulvert Structure type; must read longCulvert.
id,numCoordinates, See Table C.12.
xCoordinates,
yCoordinates
zCoordinates Double z-coordinates for
the vertical placement
of the structure.(number of values =
numCoordinates) [m AD].
allowedFlowdir String both Possible values: both, positive,
negative, none.
width Double Width of the culvert’s cross section shape [m].
height Double Height of the culvert’s cross section shape [m].
frictionType String Roughness type associated with this cross sec-
tion (see ?? for encoding).
frictionValue Double Roughness value; its meaning depends on
the roughness type selected (only used if
frictionType specified).
valveRelativeOpening * 1.0 Relative valve opening [0.0, 1.0] [-].

Remarks:
⋄ Items marked with (*) can either be a scalar value, or a time series file (<*.bc>, see more
details in Section C.12.13/(deprecated) <*.tim>) or realtime, to indicate that this parameter
gets it values supplied by, e.g., realtime control.

Deltares 432 of 562

 Attribute files

⋄ The location specification for a long culvert is only supported via x/yCoordinates or locationFile,
and these should define the actual placement of the pipe in positive flow direction (i.e., not per-
pendicular to the flow direction).
⋄ When the optional friction parameters are not set, they default to the global MDU-settings
UnifFrictType and UnifFrictCoef1D.
⋄ valveRelativeOpening is different from the normal culvert’s relOpening. The former
directly reduces the discharge through a long culvert, with respect to the fully open state.

C.12.5 1D2D Long culvert

The data block for a 1D2D long culvert structure in the <structures.ini> file is described in this section.

T
The geometrical shape is described by the parameters in the following table and these refer to the
symbols in Figure 12.11. The geometrical details are further described in Section 12.8.1.

Table C.17: Long culvert

AF Keyword
[Structure]
type
Type

String
Default Description

longCulvert Structure type; must read longCulvert.

numCoordinates, See Table C.12. Should match the coordinates
xCoordinates, of the branch.
yCoordinates
zCoordinates Double z-coordinates for
the vertical placement
of the structure.(number of values =
numCoordinates) [m AD].
allowedFlowdir String both Possible values: both, positive,
DR

negative, none.
width Double Width of the culvert’s cross section shape [m].
height Double Height of the culvert’s cross section shape [m].
branchId String Branch ID of network branch belonging to cul-
vert
csDefId String ID of cross definition belonging to culvert.
valveRelativeOpening * 1.0 Relative valve opening [0.0, 1.0] [-].

Remarks:
⋄ Items marked with (*) can either be a scalar value, or a time series file (<*.bc>, see more
details in Section C.12.13/(deprecated) <*.tim>) or realtime, to indicate that this parameter
gets it values supplied by, e.g., realtime control.
⋄ The location specification for a long culvert is only supported via x/yCoordinates, and these
should define the actual placement of the pipe in positive flow direction (i.e., not perpendicular
to the flow direction).
⋄ When the optional friction parameters are not set, they default to the global MDU-settings
UnifFrictType and UnifFrictCoef1D.
⋄ valveRelativeOpening is different from the normal culvert’s valveOpeningHeight.
The former directly reduces the flow area through a long culvert, with respect to the fully open
state, whereas the latter indirectly limits the flow via the table of loss coefficients.

C.12.6 Bridge
The data block for a bridge structure in the <structures.ini> file is described in this section. The
geometrical shape and hydraulic treatment is further described in Section 12.9.

Deltares 433 of 562

 Attribute files

Table C.18: Bridge Structure definition.

Keyword Type Default Description

[Structure]
type String bridge Structure type; must read bridge.
allowedFlowdir String both Possible values: both, positive,
negative, none.

Pillar definition:

T
pillarWidth Double Total width of pillars in cross direction [m].
formFactor Double Shape factor [-].

Abutment definition:
AF csDefId
shift
String
Double
Id of Cross-Section Definition.
Vertical shift of the cross section definition [m].
Defined positive upwards.
inletLossCoeff Double Inlet loss coefficient [-], ξi in Equation (12.57).
outletLossCoeff Double Outlet loss coefficient [-], k in Equation (12.58).
frictionType String Friction type, possible values are listed in ??.
friction Double Friction Value, used in friction loss in Equa-
tion (12.59).
length Double Length [m], L in Equation (12.59).
DR

Remarks:
⋄ At least one of the sections "Pillar definition" and "Abutment definition" must be present, but the
other is optional.
⋄ In case the "Pillar definition" is provided the effect of pillars are taken into account. In that case
all of the items in the "Pillar definition" section are required parameters
⋄ In case the "Abutment definition" is provided, the bridge results to a bridge with an own cross
section definition. In that case all of the items in the "Abutment definition" section are required
parameters
⋄ The bridge treatment is equivalent to the one known from an abutment bridge, see Section 12.9
for details.
⋄ The cross section is suggested to be an open cross section (that is, without bridge deck), but it
can be of any type, because it is merely used to compute the wet area and perimeter.
⋄ The friction and frictionType values are required in case of an abutment bridge, and
will override the cross section’s own roughness.

C.12.7 Pump
The data block for a pump structure in the <structures.ini> file is described in this section. The pump
staging and triggering, and its hydraulic treatment is further described in Section 12.11.

Table C.19: Pump definition.

Keyword Type Default Description

[Structure]
type String pump Structure type; must read pump.
orientation String positive Pump orientation. Possible values:
positive, negative.
(continued on next page)

Deltares 434 of 562

 Attribute files

Keyword Type Default Description

(continued from previous page)
controlSide String On which side[s] built-in pump triggering is ac-
tive. Only required/used when numStages >
0. Possible values:
⋄ suctionSide: Suction side control.
⋄ deliverySide: Delivery side control.
⋄ both: Suction and Delivery side control.
numStages Int 0 Number of trigger stages in pump. Set to 0 to

T
disable built-in triggering.
capacity * Pump capacity [m3 /s]. (number of values =
max(1, numStages))
startLevelSuctionSide Double[] Start level suction side [m AD]. (number of val-
ues = numStages)
AF stopLevelSuctionSide

startLevelDeliverySide Double[]
Double[] Stop level suction side [m AD]. (number of val-
ues = numStages)
Start level at delivery side [m AD]. (number of
values = numStages)
stopLevelDeliverySide Double[] Stop level at delivery side [m AD]. (number of
values = numStages)
numReductionLevels Int 0 Number of levels in reduction table.
head Double[] Head, the difference in waterlevel (delivery
side - suction side) [m]. (number of values =
numReductionLevels)
reductionFactor Double[] Reduction factor [-]. (number of values =
DR

numReductionLevels)

Remarks:
⋄ Items marked with (*) can either be a scalar value, or a time series file (<*.bc>, see more
details in Section C.12.13/(deprecated) <*.tim>) or realtime, to indicate that this parameter
gets it values supplied by, e.g., realtime control.
⋄ A pump’s orientation defines the direction of positive capacity with respect to the spatial
orientation. For example, when a pump is pumping against a network branch’s direction, it may
be convenient to set orientation = negative and use positive capacity values (as
opposed to using negative capacity values).
⋄ Built-in triggering based on stages can not be combined with time series or controlling by RTC.
Therefore, if the capacity is a time series filename or is controlled by RTC, the number of stages
(numStages) may only be equal to 0.
⋄ When built-in triggering is on (numStages > 0), then all capacity values must be nonneg-
ative (use orientation when needed). On the other hand, a (non-triggered) capacity as a
scalar, or timeseries, or via RTC may be negative.
⋄ The discharge of a 2D pump is equally distributed over the different flow links.

C.12.8 Orifice
The data block for an orifice structure in the <structures.ini> file is described in this section. The
geometrical shape and hydraulic treatment is further described in Section 12.6.

Table C.20: Orifice definition.

Keyword Type Default Description

[Structure]
(continued on next page)

Deltares 435 of 562

 Attribute files

Keyword Default Description

(continued from previous page)
type String orifice Structure type; must read orifice.
allowedFlowdir String both Possible values: both, positive,
negative, none.
crestLevel * Crest level [m AD]
P
crestWidth Double wu Crest width [m]
gateLowerEdgeLevel * Position of gate door’s lower edge. [m AD]
corrCoeff Double 1.0 Correction coefficient [-]

T
useVelocityHeight logical true Flag indicates whether the velocity height is to be
calculated or not.
useLimitFlowPos logical false Flag for setting the flow limiter for positive flow
to either unlimited or limited (false = unlimited,
true = limited).
AF limitFlowPos

useLimitflowNeg
Double

logical false
Maximum positive flow [m3 /s], only applied when
uselimitflowpos is true.
Flag for setting the flow limiter for negative flow
to either unlimited or limited (false = unlimited,
true = limited).
limitFlowneg Double Maximum negative flow [m3 /s], only applied when
uselimitflowneg is true.

Remarks:
DR

⋄ Items marked with (*) can either be a scalar value, or a time series file (<*.bc>, see more
details in Section C.12.13/(deprecated) <*.tim>) or realtime, to indicate that this parameter
gets it values supplied by, e.g., realtime control.
⋄ crestWidth is optional. Default is (the sum of) the width[s] of the flow link[s]. If the given
value is larger than this sum, it is automatically lowered to this default.
⋄ If the crestWidth of a 2d structure is smaller than the sum of the widths of the 2d links,
the crestWidth of the individual structure elements is reduced symmetrical from the outside
inwards.
⋄ The maximum flow limitation by settings (use)LimitflowPos and (use)LimitflowNeg
is further described in Table 12.6.

C.12.9 Gate
The data block for a gate structure in the <structures.ini> file is described in this section.

Table C.21: Gate definition.

Keyword Type Default Description

[Structure]
type String gate Structure type; must read gate.
crestLevel * Crest level. [m AD]
P
crestWidth Double wu Crest width. [m]
gateLowerEdgeLevel * Position of gate door’s lower edge. [m AD]
gateHeight Double Height of gate door. Needed for possible overflow
across door. [m]
gateOpeningWidth * 0.0 Opening width between gate doors, should be
smaller than (or equal to) crestWidth. Use 0.0
for a vertical door. [m]
(continued on next page)

Deltares 436 of 562

 Attribute files

Keyword Default Description

(continued from previous page)
gateOpeningHorizontal
Direction String symmetric Horizontal opening direction of gate door[s]. Pos-
sible values are: symmetric, fromLeft,
fromRight.

Remarks:

T
⋄ Items marked with (*) can either be a scalar value, or a time series file (<*.bc>, see more
details in Section C.12.13/(deprecated) <*.tim>) or realtime, to indicate that this parameter
gets it values supplied by, e.g., realtime control.
⋄ crestWidth is optional. Default is (the sum of) the width[s] of the flow link[s]. If the given
value is larger than this sum, it is automatically lowered to this default.
⋄ If the crestWidth of a 2d structure is smaller than the sum of the widths of the 2d links,
AF the crestWidth of the individual structure elements is reduced symmetrical from the outside
inwards.

C.12.10 General Structure

The data block for a general structure in the <structures.ini> file is described in this section. The
geometrical shape is described by the parameters in the following table and these refer to the symbols
in Figures 12.2 and 12.3. The hydraulic treatment is further described in Section 12.3.

For some of the keywords no default value has been specified. Then, the computational kernel of
D-Flow FM uses a value of 0.0 for these keywords. However, some of these keywords are levels
DR

(upstream1Level, upstream2Level, downstream1Level, downstream2Level), which

means that these levels are at the reference level, which is most likely an inaccurate value. Therefore,
it is important that a user pays attention to this topic of specifying values for these upstream and
downstream energy levels.

Table C.22: Specific input for the general structure.

Keyword Type Default Description

[Structure]
type String general Structure type; must read
Structure generalStructure.
allowedFlowdir String both Possible values: both, positive,
negative, none.
upstream1Width Double 10.0 wu1 [m]
upstream1Level Double 0.0 zu1 [m AD]
upstream2Width Double 10.0 wu2 [m]
upstream2Level Double 0.0 zu2 [m AD]
crestWidth Double 10.0 ws [m]
crestLevel * 0.0 zs [m AD]
crestLength Double 0.0 The crest length across the general structure.
When the crest length > 0, the extra resistance
for this structure will be ls · g/(C 2 · waterdepth).
[m]
downstream1Width Double 10.0 wd1 [m]
downstream1Level Double 0.0 zd1 [m AD]
downstream2Width Double 10.0 wd2 [m]
(continued on next page)

Deltares 437 of 562

 Attribute files

Keyword Type Default Description

(continued from previous page)
downstream2Level Double 0.0 zd2 [m AD]
gateLowerEdgeLevel * 11.0 Position of gate door’s lower edge. [m AD]
posFreeGateFlowCoeff Double 1.0 Positive free gate flow corr.coeff. cgf [-].
posDrownGateFlowCoeff Double 1.0 Positive drowned gate flow corr.coeff. cgd [-].
posFreeWeirFlowCoeff Double 1.0 Positive free weir flow corr.coeff. cwf [-].
posDrownWeirFlowCoeff Double 1.0 Positive drowned weir flow corr.coeff. cwd [-].

T
posContrCoefFreeGate Double 1.0 Positive gate flow contraction coefficient µgf [-].
negFreeGateFlowCoeff Double 1.0 Negative free gate flow corr.coeff. cgf [-].
negDrownGateFlowCoeff Double 1.0 Negative drowned gate flow corr.coeff. cgd [-].
negFreeWeirFlowCoeff Double 1.0 Negative free weir flow corr.coeff. cwf [-].
negDrownWeirFlowCoeff Double 1.0 Negative drowned weir flow corr.coeff. cwd [-].
AF negContrCoefFreeGate
extraResistance
Double
Double
1.0
0.0
Negative gate flow contraction coefficient µgf [-].
Extra resistance [-].
gateHeight Double 1d10
gateOpeningWidth * 0.0 Opening width between gate doors, should be
smaller than (or equal to) crestWidth. [m]
gateOpening ←- String symmetric Horizontal opening direction of gate door[s]. Pos-
HorizontalDirection sible values are: symmetric, fromLeft,
fromRight.
useVelocityHeight logical true Flag indicates whether the velocity height is to be
calculated or not.
DR

Remarks:
⋄ For an extensive description on these parameters see Section 12.3.
⋄ Items marked with (*) can either be a scalar value, or a time series file (<*.bc>, see more
details in Section C.12.13/(deprecated) <*.tim>) or realtime, to indicate that this parameter
gets it values supplied by, e.g., realtime control.
⋄ crestWidth is optional. Default is (the sum of) the width[s] of the flow link[s]. If the given
value is larger than this sum, it is automatically lowered to this default.
⋄ If the crestWidth of a 2d structure is smaller than the sum of the widths of the 2d links,
the crestWidth of the individual structure elements is reduced symmetrical from the outside
inwards.

C.12.11 Dambreak
The data block for a dambreak in the <structures.ini> file is described in this section. A dambreak
is not really a hydraulic structure, but it has so many similarities with hydraulic structure input that it
is also placed in the same structure file. The dam break behavior and hydraulic treatment is further
described in Section 12.2.

Table C.23: Specific input for the dambreak.

Keyword Type Default Description

[Structure]
type String dambreak Structure type; must read dambreak.
startLocationX Double x-coordinate of breach starting point.
startLocationY Double y -coordinate of breach starting point.
(continued on next page)

Deltares 438 of 562

 Attribute files

Keyword Type Default Description

(continued from previous page)
algorithm Int Breach growth algorithm. Possible values
are:
⋄ 1: van der Knaap (2000)
⋄ 2: Verheij–van der Knaap (2002)
⋄ 3: Predefined time series, see
dambreakLevelsAndWidths
crestLevelIni Double Initial breach level zcrest level [m AD].

T
breachWidthIni Double Initial breach width B0 [m].
crestLevelMin Double Minimal breach level zmin [m AD].
t0 Double Breach start time Tstart [s].
timeToBreachToMaximum ←- Double tPhase 1 [s].
Depth
AF
f1
f2
Double
Double
Factor f1 [-].
Factor f2 [-].
uCrit Double Critical flow velocity uc for erosion [m/s].
waterLevelUpstream ←- Double (optional) x-coordinate of custom up-
LocationX stream water level point.
waterLevelUpstream ←- Double (optional) y -coordinate of custom up-
LocationY stream water level point.
waterLevelDownstream ←- Double (optional) x-coordinate of custom down-
LocationX stream water level point.
waterLevelDownstream ←- Double (optional) y -coordinate of custom down-
DR

LocationY stream water level point.

waterLevelUpstreamNodeId String (optional) Node Id of custom upstream wa-
ter level point.
waterLevelDownstreamNodeId String (optional) Node Id of custom downstream
water level point.
dambreakLevelsAndWidths String (only when algorithm=3) Filename of
<*.tim> file (Section C.4) containing the
breach levels and widths.

Remarks:
⋄ The location specification for a dambreak currently only supports polyline coordinates via
x/yCoordinates or locationFile (see Table C.12).
⋄ On the same location as the dambreak polyline, a fixed weir polyline must be present (see
Section C.8).
⋄ The dambreak supports 2D grids, and also has basic support for 1D2D connections. For a 1D
river with lateral couplings to 2D flood plains, the polyline must lie alongside the river, intersect-
ing the 1D2D connections. Currently, the resolution of the 1D network must be similar to the 2D
grid resolution, i.e., typically one 1D2D link per 2D grid cell.
⋄ Breach start time t0 is considered relative to the model’s [time] RefDate (see Appendix A).
⋄ crestLevelIni is also required for time series dambreaks.
⋄ When algorithm=1, Van der Knaap(2000), currently only the default material type clay is
supported. This means that the related coefficients in Equation (12.13) are for clay (see Ta-
ble 12.3).
⋄ When algorithm=3, the time series provided in the filename via
dambreakLevelsAndWidths in minutes (also see Section C.4) are considered relative to
breach start time t0 (which is in in seconds).
⋄ When algorithm=2, Verheij–van der Knaap (2002), the up- and downstream water levels hup
and hdown are computed as the average water levels for all grid cell[s] upstream or downstream
of the breach gap, respectively.

Deltares 439 of 562

 Attribute files

Alternatively, users can specify two points so that the water levels at these points are used for hup
and hdown . (This solves any unwanted dependency on local grid cell size.) These two points can
be provided either by node Ids or coordinates. For instance, the point used for upstream water
level can be given by waterLevelUpstreamNodeId or waterLevelUpstreamLocationX.
(same for Down).

A example of a timfile for a dambreach is:

* Time breachlevel breachwidth

0 18.5 0

T
60 17.5 20
120 16.5 50
240 15.0 100
480 15.0 200
2880 15.0 200
* end input
AF
C.12.12 Compound Structure
The data block for a compound structure in the <structures.ini> file is described in this section. A
compound structure consists of a number of structures defined in the structure file that are combined
to one compound structure. The hydraulic treatment is further described in Section 12.12.

Table C.24: Specific input for the compound structure.

Keyword Type Default Description

[Structure]
type String compound Structure type; must read compound.
DR

numStructures int Number of individual structures in compound

structure.
structureIds String Semicolon separated list of structure ids.

Remarks:
⋄ structureIds is a semicolon separated list, where leading and trailing spaces will be trimmed
from each structure id in the list.
⋄ structureIds can contain spaces in the individual structure ids, no quotation is needed.
⋄ A compound structure should not contain a location specification. This will be retrieved from the
individual structures.
⋄ A compound structure does require its own id and name fields, because the output in the
history file will also contain total output for the compound’s underlying structures together and
this will appear under its own compound id.
⋄ All individual structures in a compound structure must be snapped to exactly the same flow
link[s].
⋄ The referenced individual structures may appear anywhere in the structure file.

The structure INI file is the preferred format for hydraulic structure input, and supersedes some of the
old structure quantity names in Table C.9 under "Structure parameters".

[Structure]
type = weir # Type of structure
id = weir01 # Name of the structure
locationFile = weir01.pli # *.pli; Polyline location for structure
crestLevel = weir01_crest.bc # Crest level in [m]

[Structure]
type = gate # Type of structure
id = gate01 # Name of the structure
locationFile = gate01.pli # *.pli; Polyline location for structure

Deltares 440 of 562

 Attribute files

crestLevel = gate01_crest.bc # Crest level in [m]

crestWidth = 39.5 # (Optional) Crest width in [m], between
# the fixed side walls.
gateHeight = 8.54 # Gate door height in [m], used for
# detecting flow across door.
gateLowerEdgeLevel = gate01_ledge.bc # Position of gate's lower edge in [m],
# used for flow underneath door.
gateOpeningWidth = gate01_opening.bc # (Optional) opening width between two
# sideways closing gate doors.
gateHorizontalOpeningDirection = from_left/from_right/symmetric # (Optional) Opening
# direction of the gate door(s).

[Structure]
type = pump # Type of structure

T
id = pump01 # Name of the structure
locationFile = pump01.pli # *.pli; Polyline location for structure
capacity = pump01_cap.bc # Pumping capacity in [m3/s]

C.12.13 Structure defined with a time series

AF Some quantities of a certain structure can be given as time dependent values, using a time series. We
use an example of defining a pump’s capacity as a time series, following the steps below:
⋄ 1: in the structure INI file (which was specified as StructureFile in the MDU file), when
defining a structure in one [Structure] block, specify a BC file as value of the quantity keyword.
For example, the following [Structure] block defines a pump, whose capacity is specified by
structureforcing.bc file.
[Structure]
id = Pump_bc_tim
name = Pump_bc_tim
branchId = T3_B1
DR

chainage = 1050.000
type = pump
capacity = structureforcing.bc

⋄ 2: In the specified BC file, when defining a [forcing] block, keyword name should have the
same name as the id of the structure in the structure <*.ini> file. Keyword function should
be given as timeSeries. Keyword quantity should have a quantity name, which must be
equal to one of the quantity names in Table C.25, other quantity names will not be recognized.
Using the pump example again, to specify a time series in the corresponding *.bc file, i.e. file
structureforcing.bc, the [forcing] block can be defined as below.
[forcing]
name = Pump_bc_tim
function = timeseries
time-interpolation = linear
quantity = time
unit = minutes since 2010-01-01 00:00:00
quantity = pump_capacity
unit = m3 s-1
0 0
60 0
65 1
120 1
125 2.5
180 2.5
240 0
1440 0

Remark:
⋄ Quantities of structures that can be specified as a time series are listed in Table C.25. Key-
word quantity in the *.bc file must be exactly equal to one of the quantities in Table C.25.
Otherwise it cannot be recoganized.

Deltares 441 of 562

 Attribute files

Table C.25: Quantities that can be set by a time series.

structure quantity keywords in the .bc file

pump pump_capacity
culvert culvert_valveOpeningHeight
weir weir_crestLevel
orifice orifice_crestLevel,
orifice_gateLowerEdgeLevel
longCulvert culvert_valveRelativeOpening

T
gate gate_crestLevel,
gate_gateLowerEdgeLevel,
gate_gateOpeningWidth
generalStructure general_structure_crestLevel,
general_structure_gateLowerEdgeLevel,
AF general_structure_gateOpeningWidth

C.12.14 File version history

Below are the most important file versions that have existed for the structure INI file. File versions are
formatted as <major>.<minor>. Major version changes indicate that older versions of the software are
no longer readable. Minor version changes indicate that the software can still read the older (minor)
file versions.
⋄ 3.01: Rename polylineFile to locationFile for location specification.
Note: when doing this renaming in an existing input file, all changes listed below between versions
DR

2.00 and 3.00 must also be made.

Also, add new type=gate.
⋄ 3.00: Remove bridge field bedLevel, superseded by shift.
⋄ 2.01: Add new types weir, universalWeir, culvert, bridge, pump, orifice, generalStructure,
longCulvert. Remove weir field keyword lat_contr_coeff, superseded by corrCoeff
(cf. Table 12.4).
⋄ 2.00: Add branchId+chainage or numCoordinates/xCoordinates/yCoordinates
for location specification.
Note: as of this version, using the old keyword polylineFile will disable the reading of all new
keywords and fall back to the 1.00 version reading in D-Flow FM itself.
⋄ 1.00: Consistent renaming of variables and attribute names. For pump: renamed nrStages to
numStages, reductionFactorLevels to
numReductionLevels; for culvert: renamed lossCoeffCount to numLossCoeff; for uni-
versal weir: renamed levelsCount to numLevels.
⋄ Unversioned ("0.00"): First INI-formatted version of structures.ini for D-Flow FM. No [General]
header and location specification via polylinefile only. Offer a subset of structures for 2D3D
modelling only.

C.13 Space varying wind and pressure

Warning:
⋄ This functionality contains bugs and therefore the user is advised to check the space varying
wind and pressure via the map output file. Some meteo files may contain metadata for custom
grid orientations and when misinterpreted, this can cause significantly different results. Com-
pare a wind and pressure field, at a certain time stamp on the map file, with the wind and
pressure field you supplied at that time stamp. If the space varying wind and pressure appears
to be wrong for your application, then please contact Delft3D Support.

In many cases the space varying wind data is provided as gridded data based on meteorological
stations or meteorological forecast models. This data is often defined on a different grid than the
computational grid used in D-Flow FM. Translating these files into files defined on the grid of the

Deltares 442 of 562

 Attribute files

computational engine is often a lengthy process and can result in huge files. This feature facilitates
the reading of the meteorological data on its own grid and interpolates the data internally to the grid of
D-Flow FM. D-Flow FM can handle four types of space-varying meteorological input:
1 Time- and space-varying wind on an equistant grid.
2 Time- and space-varying wind on a curvilinear grid.
3 Time- and space-varying wind on a Spiderweb grid.
4 Time- and space-varying wind in a netCDF file.

C.13.1 Meteo on equidistant grids

File contents Time-series of a space varying wind and atmospheric pressure defined on

T
an equidistant (Cartesian or spherical) grid.
File format Free formatted or unformatted, keyword based.
Generated Some offline program.

Remark:
AF ⋄ The keywords are case insensitive.

Header description for the wind velocity files:

Keywords Value Description

FileVersion 1.03 version of file format

Filetype meteo_on_equidistant_grid meteo input on equidistant grid

NODATA_value free value used for input that is to be ne-

DR

glected
n_cols free number of columns used for wind
datafield
n_rows free number of rows used for wind
datafield
grid_unit m or unit of distances on the grid
degree in both x- and y -direction

x_llcorner free x-coordinate of lower left corner of

lower left grid cell (in units specified
in grid_unit
y_llcorner free y -coordinate of lower left corner of
lower left grid cell (in units specified
in grid_unit
x_llcenter free x-coordinate of centre of lower
left grid cell (in units specified in
grid_unit
y_llcenter free y -coordinate of centre of lower
left grid cell (in units specified in
grid_unit
dx free gridsize in x-direction in units speci-
fied in grid_unit
dy free gridsize in y -direction in units speci-
fied in grid_unit
n_quantity 1 number of quantities specified in the
file

Deltares 443 of 562

 Attribute files

Keywords Value Description

quantity1 x_wind or the velocity component given in

y_wind unit unit1

unit1 m s-1 unit of quantity1: metre/second

The user must specify the location of the equidistant grid on which the meteorological data is specified.
While the user can specify the meteorological grid by means of grid cell’s corners or grid cell’s centres,

T
the meteorological data is always specified in the cell centre. If one has the location of the lower
left corner of the lower left grid cell, one can specify the starting point of the grid using keywords
x_llcorner and y_llcorner. If one has the location of the cell centre of the lower left grid cell,
one should use the keywords x_llcenter and y_llcenter. Using the first option, the first data
value is placed at (x_llcorner+ 12 dx, y_llcorner+ 12 dy ), which is the cell centre of cell (1,1). Using the
AF
latter option, the first data value is placed at (x_llcenter, y_llcenter), which is again the cell centre of cell
(1,1), i.e. the data values are always placed at the cell centres of the meteorological grid. Note that the
lower left grid cell is defined to be the grid cell with index (1,1). When using the option of meteorological
data on a separate curvilinear grid, the origin and orientation of the data set can be chosen freely with
respect to the grid on which it is specified, see section C.13.2 for details.

Time definition and data block description for the wind velocity files

Keywords Value Description

Time fixed format described below time definition string

DR

The time definition string has a fixed format, used to completely determine the time at which a dataset
is valid. The time definition string has the following format:

TIME minutes/hours since YYYY-MM-DD HH:MM:SS TIME ZONE, e.g.

360 minutes since 2008-07-28 10:55:00 +01:00

The format of the string is completely fixed. No extra spaces or tabs can be added between the different
parts of the definition. The time definition is followed by the datablock of input values corresponding to
the specified time. The data block contains values for the wind velocity in x- or y -direction for n_cols
by n_rows points, starting at the top left point. The time definition and the data block are repeated for
each time instance of the time-series.

The atmospheric pressure file

The header for the atmospheric pressure is similar to that of the wind velocity files, except for the
following differences.

Keywords Value Description

quantity1 air_pressure air pressure

unit1 Pa or mbar unit of quantity1: Pascal or mil-

libar

The specification of the time definition and the data block is fully conform the wind velocity files.

Deltares 444 of 562

 Attribute files

File version and conversion

The current description holds for FileVersion 1.03. The table below shows the latest modifications
in the file format (and version number).

FileVersion Modifications

1.03 Use of keyword Value_pos to indicate the position of the lower left corner of
the grid replaced by use of the combination of keywords:
x_llcorner and y_llcorner or

T
x_llcenter and y_llcenter

1.02 No changes for this meteo input type, but for the meteo type me-
teo_on_spiderweb_grid
1.01 Changed keyword MeteoType to FileType
AF Changed fixed value of input type (Keyword Filetype) from ArcInfo to me-
teo_on_equidistant_grid

Restrictions:
⋄ The contents of the file will not be checked on its domain.
⋄ Keywords are followed by an equal sign ’=’ and the value of the keyword.
⋄ When a keyword has value free, the value of this keyword is free to choose by the user. When
only one value is given for a keyword, this keyword has a fixed value and when 2 or more options
are shown, the user can choose between those values.
⋄ Times must be specified exactly according to the time definition. See the examples shown in
this section.
⋄ The atmospheric pressure file must use the same grid definition and time frame as the files for
DR

the wind velocity components.

⋄ The unit of the meteo grid must be the same as the computational grid, i.e. both with grid_unit
= [m] or both with grid_unit = [degree].
⋄ Input items in a data block are separated by one or more blanks.
⋄ The wind components are specified at the cell centres (water level points) of the numerical grid.
⋄ The wind components are specified in the west-east (x_wind) and south-north directions
(y_wind).

Remarks:
⋄ The time definition in the meteo files contains the number of minutes or hours since a reference
date and time in a certain time zone. The reference time and time zone may differ from those
of the simulation. During a simulation the computational engine will search in the meteo file for
the current simulation time and interpolate between neighbouring times if necessary. Possible
differences in time zone will be accounted for by shifting the meteo input data. The reference
times within the time definition string may vary in a meteo file, i.e. it is possible to attach new
input with a different reference time, behind the last data block. Consecutive times must always
be increasing in the input file.
⋄ Comments can be added after pound signs (#). These are not read.

Example of a file containing wind in x-direction (west-east)

The data blocks in this example are the result of the following FORTRAN statements:

do j = nrows,1,-1
write(out,*) (xwind(i,j),i=1,ncols)
enddo

The x-wind velocity file for a 3 (n_cols) by 4 (n_rows) grid has the following layout:

FileVersion = 1.03

Deltares 445 of 562

 Attribute files

filetype = meteo_on_equidistant_grid
NODATA_value = -999.000
n_cols = 3
n_rows = 4
grid_unit = degree
x_llcenter = -12.000
y_llcenter = 48.000
dx = 0.12500
dy = 0.083333333
n_quantity = 1
quantity1 = x_wind
unit1 = m s-1

T
TIME = 0.0 hours since 2008-01-15 04:35:00 +00:00
2 3.0 3.6
3 4.5 2
2.2 1 2.3
1.2 0.7 -0.4
TIME = 6.0 hours since 2008-01-15 04:35:00 +00:00
AF -1.1 -2.3 -3.6
-3.2 0.8 1.1
2.2 -1 -1.6
1.2 -0.7 -0.4

This results in an x-component of wind velocity given - in [m/s] - on a spherical, 3 by 4, equidistant

grid, with grid sizes given by dx and dy (in degrees) and where the centre point of the lower left cell of
the grid lies in (longitude, latitude) (-12.0, 48.0) on the globe. Data is given at two times: 0 and 6 hours
since January 15th, 2008, 4:35 AM, in UTC+0.

Remark:
⋄ The layout of the data blocks is from north to south (whereas most of the other files in Delft3D-
DR

FLOW, such as the curvilinear grid file, are ordered from south to north).
Usually the signal corresponds to Mean Sea Level. One actually wants to prescribe an input
signal corresponding to the local pressure prescribed by the space varying meteo input. To this
end, it is possible to specify an average pressure - which should correspond to your input signal
on the open boundaries - which is then used to determine local pressure gradients that need to
be applied along the open boundaries to obtain an input signal that is consistent with the local
atmospheric pressure. Using this keyword one can specify an average pressure that is used on
all open boundaries, independent of the type of wind input. The pressure must be specified in
N/m2 . An example:

C.13.2 Curvilinear data

File contents Time-series of a space varying wind and atmospheric pressure defined on
a curvilinear (Cartesian or spherical) grid.
File format Free formatted or unformatted, keyword based.
Generated Some offline program.

Remark:
⋄ The keywords are case insensitive.

Header description for the wind velocity files:

Keywords Value Description

FileVersion 1.03 version of file format

Filetype meteo_on_curvilinear_grid meteo input on curvilinear grid

NODATA_value free value used for input that is to be ne-

glected

Deltares 446 of 562

 Attribute files

Keywords Value Description

grid_file free.grd name of the curvilinear grid file on

which the data is specified
first_data_value grid_llcorner or see example below
grid_ulcorner or
grid_lrcorner or
grid_urcorner

T
data_row grid_row or see example below
grid_column

n_quantity 1 number of quantities specified in the

file
AF
quantity1 x_wind or
y_wind
the velocity component given in
unit unit1

unit1 m s-1 unit of quantity1: metres/second

Time definition and data block description for the wind velocity files
For a description of the time definition and data block see section C.13.1.

The atmospheric pressure file

DR

For a description of the atmospheric file see section C.13.1.

File version and conversion

The current description holds for FileVersion 1.03. The table below shows the latest modifications
in the file format (and version number).

FileVersion Modifications

1.03 Fixed bug in interpolation of data from meteo grid to computational grid: Con-
version script mirrored data set erroneously. This was treated correctly by me-
teo module. Fixed both the conversion script and the meteo module together:
Required modification in meteo input file:
Change first_data_value = grid_llcorner into grid_ulcorner or vice versa

or

Change first_data_value = grid_lrcorner into grid_urcorner or vice

versa
1.02 No changes for this meteo input type, but for the meteo type me-
teo_on_spiderweb_grid
1.01 Changed keyword MeteoType to FileType

Changed keyword Curvi_grid_file to Grid_file

Changed fixed value of input type (Keyword Filetype) from Curvi to me-
teo_on_curvilinear_grid

Restrictions:

Deltares 447 of 562

 Attribute files

⋄ The restrictions for space varying wind and pressure on a separate curvilinear grid are the same
as for space varying wind and pressure on an equidistant grid, described in section C.13.1. A
differerence is that the data values on the curvilinear grid are not specified in the cell centres,
but in the grid points (cell corners).
⋄ The unit of the meteo grid must be the same as the computational grid, i.e. both with grid_unit
= [m] or both with grid_unit = [degree].

Remark:
⋄ The remarks for space varying wind and pressure on a separate curvilinear grid are the same
as for space varying wind and pressure on an equidistant grid, described in section C.13.1.

T
AF
DR

Figure C.1: Illustration of the data to grid conversion for meteo input on a separate curvi-
linear grid

Example:
A file for input of x-velocity (in west-east direction) on a 4 (n_rows) by 5 (n_cols) curvilinear grid, where
the meteorogical data is mirrored vertically with respect to the grid, has the following layout:

FileVersion = 1.03
filetype = meteo_on_curvilinear_grid
NODATA_value = -999.000
grid_file = curviwind.grd
first_data_value = grid_llcorner
data_row = grid_row
n_quantity = 1
quantity1 = x_wind
unit1 = m s-1
TIME = 0.0 minutes since 1993-06-28 14:50:00 -02:00
1 2 3 4 5
6 7 8 9 10
11 12 13 14 15
16 17 18 19 20
TIME = 600.0 minutes since 1993-06-28 14:50:00 -02:00
1 2 3 4 5
6 7 8 9 10
11 12 13 14 15
16 17 18 19 20

This results in an x-component of velocity given - in [m/s] - on the curvilinear grid specified in file

Deltares 448 of 562

 Attribute files

<curviwind.grd>. The data set will be mirrored such that the first value of the data (upper left corner,
in the example ’1’) corresponds to the lower left corner of the grid (point (1,1)) and a row of data
corresponds to a row on the grid, see Figure C.1. Data is given at two times: 0 and 600 minutes since
June 28th, 1993, 14:50 PM, in UTC-2.

C.13.3 Spiderweb data

Remarks:
⋄ The spiderweb file format used in D-Flow FM forms a subset of the the format described be-
low. The extensive format is accepted by D-Flow FM, but not all keywords are required and/or
meaningful.

T
⋄ The keywords grid_unit and air_pressure_reference are ignored.
⋄ The keyword n_quantity is ignored; the number of quantities is always 3.
⋄ The keywords quantity1, quantity1 and quantity1 are ignored, the order of the vari-
ables in the file is assumed to be wind speed, wind direction and pressure drop.
⋄ The keywords unit1 and unit2 are ignored.
AF ⋄ The keyword unit3 is optional; if omitted or different from ’mbar’, Pa is silently assumed

Cyclone winds are governed by a circular motion, combined with a cyclone track. This type of wind
is generally very difficult to implement on a curvilinear grid. This feature facilitates the reading of the
so-called Spiderweb files and interpolates the wind and pressure data internally to the computational
grid. A special feature of the space varying wind and pressure on the Spiderweb grid is that it can
be combined with one of the other meteorological input options described in this manual, i.e. to either
uniform wind and pressure, or to one of the space varying wind and pressure options, see section C.13.
File contents Time-series of a space varying wind and atmospheric pressure defined on
a Spiderweb grid. This grid may be specified in Cartesian or spherical
coordinates.
File format Free formatted or unformatted, keyword based.
DR

Generated Some offline program.

Remarks:
⋄ The keywords are case insensitive.
⋄ Space varying wind and pressure on a Spiderweb grid is added to other wind input and the wind
fields are interpolated and combined in and around the cyclone.

Header description of the Spiderweb wind and pressure file:

Keywords Value Description

FileVersion 1.03 version of file format

Filetype meteo_on_spiderweb_grid meteo input on Spiderweb grid

NODATA_value free value used for input that is to be ne-

glected
n_cols free number of gridpoints in angular di-
rection
n_rows free number of gridpoints in radial direc-
tion
grid_unit m or unit of the Spiderweb grid
degree

spw_radius free radius of the spiderweb given in units

given by spw_rad_unit
spw_rad_unit m unit of the Spiderweb radius

Deltares 449 of 562

 Attribute files

Keywords Value Description

spw_merge_frac [0.0,1.0] fraction of the Spiderweb radius

where merging starts of the back-
ground wind with the Spiderweb
wind. Default is 0.5
air_pressure air_pressure_default_from Both keyword and value are too
_reference _computational_engine long to fit on one line.
Reference value related to p_drop is
the default air pressure of the com-

T
putional engine
or free or the value specified.
If missing, p_drop is extracted from
the actual atmospheric pressure.
AF
n_quantity

quantity1
3

wind_speed
number of quantities specified in the
file
wind speed given in unit unit1

quantity2 wind_from_direction direction where the wind is coming

from given in unit unit2
quantity3 p_drop drop in atmospheric pressure given
in unit unit3
unit1 m s-1 unit of quantity1: metres/second

degree unit of quantity2: degrees

DR

unit2

unit3 Pa or unit of quantity3: Pascal or

mbar millibar

Time definition and data block description

For a description of the time definition see section C.13.1.

Cyclone track information:

For each time in the time series of space varying wind and pressure on a Spiderweb grid, the position
of the cyclone eye (and thus also the spiderweb grid) must be given, as well as the drop of atmospheric
pressure in the cyclone eye.

File version and conversion

The current description holds for FileVersion 1.03. The table below shows the latest modifications
in the file format (and version number).

Deltares 450 of 562

 Attribute files

T
AF
Figure C.2: Wind definition according to Nautical convention
DR

Figure C.3: Spiderweb grid definition

Deltares 451 of 562

 Attribute files

FileVersion Modifications

1.03 No changes for this meteo input type

1.02 Changed the use of keyword n_rows and n_cols. The radius of the cyclone
is divided in n_rows rings of width: spw_radius/n_rows [m] and the circle is
divided in n_cols parts of 2π/n_cols [rad].
1.01 Changed keyword MeteoType to FileType

Changed fixed value of input type (Keyword Filetype) from Spiderweb to

meteo_on_spiderweb_grid

T
Restriction:
⋄ The restrictions for space varying wind and pressure on a Spiderweb grid are the same as for
space varying wind and pressure on an equidistant grid, described in section C.13.1.
AF
Remarks:
⋄ The remarks for space varying wind and pressure on a separate curvilinear grid are the same
as for space varying wind and pressure on an equidistant grid, described in section C.13.1.
⋄ The Spiderweb grid is circular and the definitions of the number of rows n_rows and the num-
ber of columns n_cols is therefore different then for the other meteo input formats. For the
Spiderweb grid, the number of rows determines the grid size in radial direction. The number of
columns defines the grid size in angular direction. See Figure C.3.
⋄ The wind is specified according to the nautical convention, i.e. wind from the true North has
direction zero and the wind turns clockwise with an increasing angle. See Figure C.2.

Example:
DR

A file for input of space varying wind and pressure on a 5x3 Spiderweb grid, has the following layout:

FileVersion = 1.03
filetype = meteo_on_spiderweb_grid
NODATA_value = -999.000
n_cols = 3
n_rows = 5
grid_unit = degree
spw_radius = 600000.0
spw_rad_unit = m
air_pressure_reference = air_pressure_default_from_computational_engine
n_quantity = 3
quantity1 = wind_speed
quantity2 = wind_from_direction
quantity3 = p_drop
unit1 = m s-1
unit2 = degree
unit3 = Pa
TIME = 0.0 hours since 1997-07-14 03:00:00 -06:00
x_spw_eye = 115.1
y_spw_eye = 18.9
p_drop_spw_eye = 5300.0
1.38999 1.38261 1.38315
1.28251 1.34931 1.22571
1.27215 1.31214 1.32451
1.38999 1.86592 2.87732
1.43899 1.24912 2.21519
60.0000 180.0000 270.0000
28.7500 20.0000 31.2500
42.5000 53.7500 65.0000
49.3400 60.2400 81.5200
51.4100 62.0000 43.1200
5301.280 5294.490 5156.240
5043.460 5112.040 5264.020

Deltares 452 of 562

 Attribute files

5140.020 5202.520 5411.210

5294.730 5285.760 5235.250
5242.530 5156.190 5124.240
TIME = 1.0 hours since 1997-07-14 03:00:00 -06:00
x_spw_eye = 114.8
y_spw_eye = 18.8
p_drop_spw_eye = 5250.0
1.35763 1.35763 1.35763
1.35763 1.87273 2.24784
1.92214 2.47836 2.17266
1.87662 2.72116 2.82375
1.26585 2.24146 2.38722

T
159.0000 346.5200 290.6400
342.3200 282.1400 20.2400
10.7500 25.5300 36.4500
61.8400 81.6200 45.5100
49.5250 56.7500 75.1300
5314.520 5104.490 5287.240
AF 5124.240
5152.460
5242.020
5244.270
5285.760
5247.040
5223.520
5211.210
5252.420
5222.020
5475.210
4998.110

This results in the following set of meteo data. Velocities given in [m/s] and pressure drops in [Pa] on
a Spiderweb grid which is given in spherical coordinates (grid_unit = degree). The cyclone and
spiderweb grid have a radius of 600 km. The grid is 5x3, which means the radius is divided in five
parts of 120 km and the 360 degrees are divided in 3 parts of 120 degrees each. Wind speeds, wind
directions and pressure drops are given at two times: 0 and 1.0 hour since July 14th, 1997, 03:00 AM,
in UTC-6. Between these two times the cyclone eye moves from (longitude, latitude) (115.1, 18.9) to
(114.8, 18.8) on the globe and the pressure drop in the cylcone eye decreases from 5300.0 [Pa] to
DR

5250.0 [Pa].

C.13.4 Meteo on a netCDF file

Scalar meteorological forcing variables can be provided as gridded fields in NetCDF files. The file and
metadata details are described in Section E.2.4.2.

C.14 Statistical output (Fourier, minimum, maximum and average)

File contents All parameters required to execute an online statistical analysis for speci-
fied quantities, a specified period and for specified frequencies. This anal-
ysis can be a Fourier analysis or another form of statistical analysis e.g.
computation of the minimum, maximum or average value.
Filetype ASCII
File format Fix formatted for text variables, free formatted for real and integer values.
Filename <name.fou>
Generated Manually offline

Each line in the file represents a record.

Deltares 453 of 562

 Attribute files

Record description:

Record Record description

each line
1 Id of the quantity on which the analysis is to be performed:
bs bed stress (1D/2D field)
cn n-th constituent in the MDU-file
cs salinity, will be skipped if temperature is not modelled
ct temperature, will be skipped if temperature is not modelled

T
eh energy height (1D/2D field)
fb freeboard (1D only)
q1 discharge through a flow link
sul water levels at a flow links (1D/2D field)
ux velocity in x-direction
AF uxa
uy
uya
uc
velocity in x-direction, column average (1D/2D field)
velocity in y-direction
velocity in y-direction, column average (1D/2D field)
velocity magnitude
vog volume on ground (1D only)
wd water depth (1D/2D field)
wdog waterdepth on ground (1D only)
wl water level (1D/2D field)
ws wind magnitude (1D/2D field)
2 Analysis start time, tstart, in Tunit [seconds, minutes, hours] after the
simulation Reference Date. Use −1 to indicate the simulation start time.
3 Analysis stop time, tstop, in Tunit [seconds, minutes, hours] after the
simulation Reference Date. Use −1 to indicate the simulation stop time.
DR

4 Integer number of cycles (i.e. mode) within the analysis time frame. Alter-
natively, the length of the running mean filter.
5 Nodal amplification factor.
6 Phase shift [degrees].
7 Layer number for the analysis of 3D quantities. This number should if and
only if the selected quantity is not marked as a 1D or 1D/2D field. When
specified, it should be a valid layer number. However, this value is currently
not used. In 3D models, the analysis is done on the whole 3D field, ignoring
the layer number.
8 Flag specifying the type of the analysis:
⋄ default (no keyword): perform Fourier analysis
⋄ min/max/avg, requests the computation of the minimal, maximal or
average of the selected quantity over the selected period. The num-
ber of cycles now is the length of an optional running mean filter. An
additional quantity id can be supplied to report the requested quantity
when the min/max of that additional quantity occurs (see last record of
Example 2, extensions for min/max).
⋄ last, requests the last value, e.g. when anticipating convergence to a
steady-state solution. The number of cycles now is the number of time
steps before the end of the analysis period to average.
⋄ time below / time above followed by threshold value, requests
the computation of the total time passed during which the selected
quantity strictly below or above the specified threshold.

Remarks:
⋄ The analysis is performed for all grid points individually.
⋄ If the number of cycles is set equal to 0, the mean value of the quantity over the interval specified
by the start and stop time is determined.
⋄ The computed Fourier amplitudes differ slightly from the amplitude of the corresponding tidal
component. When comparisons with co-tidal maps have to be made, this factor can be deter-

Deltares 454 of 562

 Attribute files

mined using the subsystem ASCON of Delft3D-TIDE, the tidal analysis package of Deltares.
⋄ The computed Fourier phases are by default associated with the reference date/time of the
FLOW simulation. For comparisons with co-tidal maps the user may specify a non-zero phase
shift.
⋄ For computational cells which are dry during all Fourier cycles, no values are associated, and
hence they contain a missing value.
⋄ The layer number should not be specified for 1D or 1D/2D quantities such as water levels. In
3D models, the analysis is done on the whole 3D field, ignoring the layer number.
⋄ In case of max and min, this keyword maybe followed by the keyword time to indicate that
also the time at which the maximal or minimal value occurs, should be written to file.
⋄ In case of max computation for water level, water depth or energy height, an additional keyword

T
inidryonly can be specified to perform the analysis only for points that are initially dry.
⋄ Depending on the flag FouUpdateStep the analysis is done every user time step
(FouUpdateStep = 0, default), or every computation time step (FouUpdateStep = 1),
or with the same time step as the history output (FouUpdateStep = 2). The keyword
FouUpdateStep is defined in the chapter [output] of the mdu-file.
AF
Restrictions:
⋄ If FouUpdateStep = 0 or 2, the start and stop times of the analysis frame specified must
be a multiple of the user time step or the history output time step.
⋄ The start and stop times of the analysis frame specified must be a valid time, i.e. must fit in the
simulation time frame of the FLOW computation.
⋄ Items in a record must be separated by one or more blanks.
⋄ The quantity name (first item on a line) must start on position one.
⋄ The starting time of the simulation is excluded from the analysis.

Running mean
DR

The minimum and maximum values may be filtered with a running mean filter, to minimize the effect of
spikes. Column 4 is used for this and is the length of the filter in fourier output time steps. Therefore,
this option can only be used if FouUpdateStep = 0 or 2.

The running mean filter is defined by:

Suppose we have a time serie x[1], x[2], ...x[N ].
Then the running mean is:
x[i] = (x[i + 1 − L] + x[i + 2 − L] + .. + x[i])/L, with L the length of the filter and i ≥ L ∧ L > 0.

The minimum of the running mean is defined as: min x[i], i ∈ [tstart, tstop], the same holds for other
functions.

The running mean filter is applied for all points in the model. Note that we need a buffer of length L
times the number of grid points to calculate this. This buffer is needed for each quantity in the fou-file
using the running mean, except if you ask both the min and max for the same field with the same start
and stop time. Then the same buffer is used.

It is possible to get the velocity at the moment that we have the highest water level, or the time of the
maximum water level (see the last two records of Example 2, extensions for min/max). Or just the
latest time(s), in case you are running to a steady state solution (check out the last option).

Deltares 455 of 562

 Attribute files

Example 1
A statistical analysis is requested for:
⋄ Water level: mean value and the first two harmonics.
⋄ Velocity in x-direction: first harmonic, in the top layer.
⋄ Velocity in y -direction: first harmonic, in the top layer.
⋄ Velocity magnitude: first harmonic, in the top layer.
⋄ Temperature: first harmonic, in the third layer.
⋄ Salinity: mean value of the third layer.
⋄ Four constituents: mean value for a slightly shifted time period in the top layer for 3 constituents;
and the maximum for the fourth constituent.

T
wl 720. 1440. 2 1.000 0.000
wl 720. 1440. 1 1.000 0.000
wl 720 1440. 0 1.000 0.000
ux 720. 1440. 1 1.000 0.000 1
uy 720. 1440. 1 1.000 0.000 1
AF uc
ct
cs
c1
720.
720.
720.
710.
1440.
1440.
1440.
1430.
1
1
0
0
1.000
1.000
1.000
1.000
0.000
0.000
0.000
0.000
1
3
3
1
c2 710. 1430. 0 1.000 0.000 1
c3 710. 1430. 0 1.000 0.000 1
c4 710. 1430. 0 1.000 0.000 1 max

Remark:
⋄ In this example the start and stop times are in minutes because the Tunit of this model (as
defined in the MDU file) is in minutes.
DR

Example 2, extensions for min/max

A statistical analysis is requested for:
⋄ Water level: maximum with a filter with length 25, starting t = 720.
⋄ Water level: minimum with a filter with length 13, stopping at t = 1440.
⋄ Water level: average for the last 5 steps of the simulation.
⋄ Water level: maximum with a filter with length 25, with extra output of the time at which this maxi-
mum occurs.
⋄ Velocity magnitude as the water level reaches this maximum, starting at t = 720 and stopping at t
= 1440.

wl 720. -1 25 1.000 0.000 max

wl -1 1440. 13 1.000 0.000 min
wl -1 -1 5 1.000 0.000 last
wl -1 -1 25 1.000 0.000 max time
uc 720. 1440. 1 1.000 0.000 1 max wl

Remarks:
⋄ In this example the start and stop times are in minutes because the Tunit of this model is in
minutes. A start time of −1 means start of the simulation; A stop time of −1 means the end of
the simulation.
⋄ In this example the columns 5 and 6 are completely ignored.
⋄ Quantities that give combined results, must have the same dimension. Therefore we introduced
sul (water level at flow links) to compute q1 (discharge through flow link) at the time of the
maximum water level. Note that this combination does not work for 3D applications.

C.15 Cache file

A cache file may be used to speed up the initialization of a model significantly. It is automatically filled
with the geometrical discretization of some spatial input of a model schematization. The name of this

Deltares 456 of 562

 Attribute files

file is always equal to <mdu_name.cache> and located in the same directory as the mdu-file. It is a
binary file.

The currently supported model features for caching are:

⋄ Fixed weirs (see Section 12.1);
⋄ Observation points (see Section 7.4.2.2).
⋄ Observation cross-sections (see section 7.4.2.3).
⋄ Dry points and dry areas (see Section 7.4.2.7)
⋄ Thin dams (see Section 7.4.2.4)

T
In principle, caching can also be applied to other features like weirs, gates, sources/sinks and embank-
ments. However, in practice we observe that in general the initialization of these features isn’t time
consuming. Therefore, caching hasn’t been implemented for these features. On the other hand, in
AF particular for fixed weirs the initialization can be time consuming.

The behavior of caching is as follows:

1 Upon initialization of the model, when a cache file is present, it is checked on the following require-
ments:
⋄ The file version of the cache file should match the one supported by the current D-Flow FM
version, see Section C.15.1
⋄ The MD5 hash stored in the cache file should match the one of the current NetFile.
⋄ The cached count of observation points and their x- and y -coordinates should match the cur-
rent set of observation points.
⋄ The cached count of fixed weirs and their x- and y -polyline coordinates should match the
current set of fixed weirs.
2 If any of these checks fail, the cache file is entirely ignored. In this case (and also when no cache
DR

file is present at all) the model input is completely initialized onto the model grid. The result is then
saved in the same (or new) cache file, for a future model run.
3 If all checks succeeded, the feature discretization is skipped, and instead directly loaded from the
cache file.

Caching can be enabled or disabled via the MDU setting UseCaching=1 or 0, respectively. The de-
fault or MDU setting for caching can be disabled from the commandline using the option --no-geom-cache.

The cache file is platform-independent and as such can be transferred to other hosts, along with the
entire set of model input files.

The cache file should not be edited in any way.

The default value is UseCaching=1, which means that caching is applied automatically. Although
there is no reason for this, it is possible to switch off caching via keyword UseCaching=0.

C.15.1 File version and description

The description here holds for the current FileVersion 1.01. The table below shows the latest
modifications in the features being cached and version number.

FileVersion Description

1.00 Features being cached: fixed weirs, observation points, observation cross-
sections, dry points and dry areas
1.01 Added to cache: thin dams

Deltares 457 of 562

 D Initial conditions and spatially varying input

D.1 Introduction
Spatially varying input is input data that varies in space, not in time, such as initial conditions (water
levels, etc.), or spatially varying model parameters (friction coefficients, etc.). D-Flow FM uses input
data in model-independent coordinates, that is, the input files should contain their own spatial coor-
dinates, and do not correspond with the D-Flow FM grid cell numbering. As a result, the model grid
can always be changed, without the need to change all other spatial input. The spatial input will be
interpolated onto the active model grid. Spatial input has to be specified in the ext-file (section C.6).
All supported quantities are listed in Table C.9 under “Initial fields” and “Spatial physical properties”.

T
Remark:
⋄ Spatial input has to be specified in the IniFieldFile (section D.2). Formerly, this was
specified in the old-style ext-file, which is now only available for backwards compatibility.

Initial conditions can also be set using a restart-file, which assigns the exact values in the file to the
AF current model grid. No interpolation is performed, and the restart file should correspond exactly with the
current model. This is completely unrelated to the remainder of this chapter; please consult Section 8.8
instead.

D.2 Initial and parameter fields

Initial and parameter fields are (almost always) time-independent spatial fields that can describe initial
conditions and spatially varying model parameters. The name of this file is specified using the keyword
IniFieldFile in the MDU-file (see Appendix A). This file supersedes the old-style external forcings
file for these quantities.

The fields are specified in the ini-file format. The order of blocks is relevant, since multiple data sets
DR

maybe combined for the same quantity (see operand in Table D.1). The order of keywords within
a block is not relevant. Keywords and constants are case insensitive, but camel case is used as a
naming convention. String values (e.g., filenames) are case sensitive.

This file may contain one or more Initial blocks or Parameter blocks, each followed by a set of keywords
that specify the spatial data for that field. See the following table for details.

Table D.1: Initial and parameter fields.

Keyword Type Default Description

[General]
fileVersion String 3.00 File version. Do not edit this.
fileType String iniField File type. Do not edit this.

[Initial] or Repeat as needed

[Parameter]
quantity String Name of the quantity, see Table D.2 hereafter.
dataFile String Name of file containing the field data values.
dataFileType String Type of dataFile. Supported types:
⋄ ArcInfo
⋄ GeoTIFF (section D.4.3)
⋄ sample (section C.3)
⋄ polygon (section C.2)
(continued on next page)

Deltares 458 of 562

 Initial conditions and spatially varying input

Keyword Type Default Description

(continued from previous page)
interpolationMethod String Type of (spatial) interpolation. Supported
methods:
⋄ constant, only with
dataFileType=polygon.
⋄ triangulation, Delaunay triangula-
tion+linear interpolation.
⋄ averaging, grid cell averaging.

T
operand String O (optional) How this data is combined with pre-
vious data for the same quantity (if any). Sup-
ported operands:
⋄ O, override any previous data.
⋄ A, append, sets only where data is still
missing.
AF ⋄ +, adds the provided values to the existing
values.
⋄ *, multiplies the existing values by the pro-
vided values.
⋄ X, takes the maximum of the existing val-
ues and the provided values.
⋄ N, takes the minimum of the existing val-
ues and the provided values.
averagingType String mean (optional) Type of averaging, if
interpolationMethod=averaging.
Supported types:
DR

⋄ mean, arithmetic mean

⋄ nearestNb, nearest neighbour value
⋄ max, highest
⋄ min, lowest
⋄ invDist, inverse-distance-weighted av-
erage
⋄ minAbs, smallest absolute value
⋄ median, median value
averagingRelSize Double 1.01 (optional) Relative search cell size for averag-
ing.
averagingNumMin Integer 1 (optional) Minimum number of points in aver-
aging. Must be ≥ 1.
averagingPercentile Double 0.0 (optional) Percentile value for which data val-
ues to include in averaging. 0.0 means off.
extrapolationMethod Logical no Option for (spatial) extrapolation: no or yes.
locationType String all (optional) Target location of interpolation, if
quantity is 1d2d distinction possible (see
Table D.2). Supported locations:
⋄ 1d, interpolate only to 1d nodes/links
⋄ 2d, interpolate only to 2d nodes/links
⋄ all, interpolate to all nodes/links
value Double (optionally required) Only for
dataFileType=polygon. The con-
stant value to be set inside for all model
points inside the polygon.
frictionType String (optional) Only for
quantity=frictionCoefficient.
See remark below.

Deltares 459 of 562

 Initial conditions and spatially varying input

Remark:
⋄ Friction coefficients may be provided of a different type than the model global type (i.e., MDU set-
ting UnifFrictCoef). To do so, add the extra keyword frictionType to the [Parameter]
block. Valid values are listed below:
⋄ Chezy: Chézy C [m1/2 /s]
⋄ Manning: Manning n [s/m1/3 ]
⋄ wallLawNikuradse: Nikuradse kn [m]
⋄ WhiteColebrook: Nikuradse kn [m]
⋄ StricklerNikuradse = Nikuradse kn [m]
⋄ Strickler: Strickler ks [m1/3 /s]
⋄ DeBosBijkerk: De Bos-Bijkerk γ [1/s]

T
Example:

# comments
AF [Initial]
quantity
dataFile
dataFileType
=
=
=
initialWaterlevel
iniwaterlevels.asc
ArcInfo
interpolationMethod = triangulation
locationType = 2d

[Initial]
quantity = bedlevel
dataFile = inibedlevel.ini
dataFileType = 1dField

[Parameter]
quantity = frictioncoefficient
dataFile = manning.xyz
DR

dataFileType = sample
interpolationMethod = triangulation

[Parameter]
quantity = frictioncoefficient
dataFile = calibration1.pol
dataFileType = polygon
interpolationMethod = constant
value = 0.03
operand = *

D.3 Supported quantities

D.3.1 Accepted quantity names in initial field files

The list of accepted quantity names in initial field files is subdivided into two categories:
⋄ Initial fields
⋄ Spatial model parameters

Table D.2 shows the accepted quantity names, the corresponding names in old external forcing files,
the expected units, the possibility of 1d/2d distinction and on which page to find more details. 1d/2d
distinction allows to limit a dataset to either the 1D grid points, or 2D, or allow both. This is achieved
by setting the locationType parameter in the same data block.

Deltares 460 of 562

 Initial conditions and spatially varying input

Table D.2: List of accepted field quantity names in initial field file.

Quantity Name in old external forcing Unit 1d/2d dis- Page

file tinction
possible?
Initial fields:
bedLevel bedlevel, [m] yes
bedlevel1D,
bedlevel2D
initialWaterLevel initialwaterlevel, [m] yes 462

T
initialwaterlevel1d,
initialwaterlevel2d
initialWaterDepth N/A [m] yes
initialSalinity initialsalinity [ppt] yes 462
1
initialSalinityTop initialsalinitytop [ppt] yes 462
AF
initialSalinityBot
initialVertical ←-
SalinityProfile
initialsalinitybot
initialvertical ←-
salinityprofile
[ppt]
[ppt]
yes
no
462
462

initialTemperature initialtemperature [◦ C] yes 463

InitialVertical ←- initialvertical ←- [◦ C] no 463
TemperatureProfile temperatureprofile
initialTracer ←- initialtracer ←- yes 463
<tracername> <tracername>

initialSedfrac<name> [kg/m3 ]
DR

initialSedFrac<name> N/A 40
3
initialVertical ←- initialvertical ←- [kg/m ] N/A 40
SedFracProfile<name> sedfracprofile<name>
initialVertical ←- initialvertical ←- [kg/m3 ] N/A 40
SigmaSedFrac ←- sigmasedfrac ←-
Profile<name> profile<name>
initialUnsaturated ←- initialunsatured ←- [m] no
ZoneThickness zonethickness
N/A initialvelocity [m/s, m/s] no
initialVelocityX initialvelocityx [m/s] no 462
initialVelocityY initialvelocityy [m/s] no 462
Spatial model parameters: 463
frictionCoefficient frictioncoefficient depends N/A
on its type,
see Sec-
tion 3.3.6
or friction ←-
_coefficient ←-
_time_dependent
horizontalEddyVis ←- horizontaleddyvis ←- [m2 /s] Intended
cosityCoefficient cositycoefficient for 2D
only
horizontalEddyDif ←- horizontaleddydif ←- [m2 /s] N/A
fusivityCoefficient fusivitycoefficient

1
initialSalinityTop and initialSalinityBot can not be combined. Only one can be given per
model, and must be combined with initialSalinity.

Deltares 461 of 562

 Initial conditions and spatially varying input

Quantity name in old external forcing Unit 1d/2d dis- Page

file tinction
possible?

advectionType advectiontype [-] N/A See AdvecType in Table A.1

bedLevelType ibedlevtype [-] N/A 318
InterceptionLayer ←- N/A [m] yes ??
Thickness
PotentialEvaporation N/A [mm/hr] yes ??

T
2
InfiltrationCapacity infiltrationcapacity [mm/day] yes ??
HortonMaxInfCap3 N/A [mm/hr] yes ??
HortonMinInfCap N/A [mm/hr] yes ??
HortonDecreaseRate N/A [1/hr] yes ??
AF HortonRecoveryRate
bedrockSurface ←-
Elevation
N/A
bedrock_surface ←-
_elevation
[1/hr]
[m]
yes
no
??
Subsidence and uplifting

D.3.2 Water levels

Water levels can be provided through all file types listed in section D.4 (except for vertical profiles,
obviously). The restart file sets the water level both at the old and new time step. Non-restart files
should be specified using quantity=initialWaterlevel.
DR

D.3.3 Initial velocities

Initial velocities are recommended to be set via restart files, such that they exactly correspond with the
model’s waterdepths. They can also be set in the IniFieldFile, using quantity=initialVelocityX/Y,
but this is not advised.

D.3.4 Salinity
Salinity concentrations from non-restart files are possible as spatially varying in the horizontal plane
and with two depth options:
⋄ depth-averaged values, so as a 2D scalar field (in case of 3D models applied uniformly in the
vertical);
⋄ or (for 3D models) as linearly interpolated values between a top layer concentration and a bottom
layer concentration. This is achieved by specifying two quantity blocks: initialSalinityTop
and initialSalinity, respectively;
⋄ or (for 3D models) a scalar 2D field constant in the vertical below a depth. This is achieve by
providing at least a quantity block with initialSalinityBot, and the extra parameter
uniformSalinityBelowZ = ....

For 3D models, alternatively, spatially constant, but depth-varying salinities can be set using the
quantity=verticalsalinityprofile, and a vertical profile file (see section D.4.4).

2
Only for constant infiltration (InfiltrationModel = 2).
3
Only for Horton infiltration (InfiltrationModel = 4).

Deltares 462 of 562

 Initial conditions and spatially varying input

D.3.5 Temperature
Temperature values from non-restart files are possible as depth-averaged values, using quantity=temperature.

For 3D models, alternatively, spatially constant, but depth-varying temperatures can be set using the
QUANTITY=verticaltemperatureprofile, and a vertical profile file (see section D.4.4).

D.3.6 Tracers
Initial tracer concentrations from non-restart files are similar to temperature values, now specified using
quantity=tracer<tracername>. The set of tracer name(s) is not listed in the MDU-file explicitly,

T
they are inferred from all supplied initial tracer definitions and the tracer boundary conditions (see also
section E.1.7). The <tracername> postfix can uniquely associate an initial tracer quantity with a
tracerbnd quantity.

D.3.7 Sediment
AF Initial sediment concentrations for the Delft3D-MOR-based sediment transport module (see section 4.4
for an explanation) is via the <∗.sed> file. See the Deltares (2025d) for further details.

D.3.8 Physical coefficients

A second group of spatially varying input are the physical and numerical coefficients listed below. They
allow changing of model parameters in space or in certain sub-regions of the domain, and as such
these values override the uniform values from the MDU file. The input data can come from the inside-
polygon file type (section D.4.1, the sample file type (section D.4.2), or the GeoTIFF raster file type
(section D.4.3).
DR

quantity name MDU uniform equivalent description

frictioncoefficient UnifFrictCoef Friction coefficient (use IFRCTYP and

UnifFrictType, resp. to set the fric-
tion type.

horizontaleddy... Vicouv Horizontal eddy viscosity coefficient

...viscositycoefficient (m2 /s).

horizontaleddy... Dicouv Horizontal eddy diffusivity coefficient

...diffusivitycoefficient (m2 /s).

advectiontype AdvecType Type of advection scheme.

ibotlevtype BedlevType Type of bed-level handling.

D.4 Supported file formats

All file formats below, except for restart files, are in model-independent coordinates and will be cropped
and/or interpolated onto the model grid.

Deltares 463 of 562

 Initial conditions and spatially varying input

D.4.1 Inside-polygon option

A spatially constant value in a restricted part of the domain can be set by specifying a polygon file
(section C.2) in the ext-file as follows:

QUANTITY=frictioncoefficient
FILENAME=winterbed.pol
FILETYPE=10
METHOD =4
VALUE =55

T
IFRCTYP =1 # Optional, override uniform [physics] UnifFrictType=..

The interpolation option METHOD=4 simply specifies the no-interpolation is to be performed, only
inside-polygon cropping. For QUANTITY=frictioncoefficient the default friction type may be
AF
D.4.2
overridden with the keyword IFRCTYP.

Sample file
Spatial data from sample files (<∗.xyz>, see section C.3) is interpolated by triangle interpolation or
sample averaging. The following options control the type of interpolation:

interpolation options description

method

METHOD=5 Triangle interpolation

DR

EXTRAPOLTOL=20 Allow extrapolation from convex hull of sam-

ples up to . . . meters (default: 0).

METHOD=6 Sample averaging inside control volumes:

AVERAGINGTYPE=1 Normal (unweighted) averaging

AVERAGINGTYPE=2 Nearest neighbour

AVERAGINGTYPE=3 Maximal value

AVERAGINGTYPE=4 Minimal value

AVERAGINGTYPE=5 Inverse weighted distance averaging

AVERAGINGTYPE=6 Minimal absolute value (Use with care. It

takes the absolute value.)

RELATIVESEARCHCELLSIZE Control size of search volume: 1=actual

=... cell, 1.5=50 % larger in all directions.

D.4.3 GeoTIFF file

GeoTIFF4 is a file format for georeferenced rasterized datasets. When providing a GeoTIFF file as
an initial or parameter field (Section D.2), the model coordinate system in that file must match the
coordinate system of the D-Flow FM model (e.g., geographic or projected coordinates). Also, only
single layer (or band) files are currently supported.

4
https://trac.osgeo.org/geotiff/

Deltares 464 of 562

 Initial conditions and spatially varying input

D.4.4 Vertical profile file

Initial values that are constant in 2D space, but vary in depth can be specified using vertical profile
files, which are basic polyline files (section C.2). For example for a linearly varying salinity from 30 to
20 ppt from -10 to 0 m :

L1
2 2
-10 30
0 20

T
AF The METHOD keyword must be specified, but is further ignored: linear interpolation is always used.

D.4.5 Map file

Initial field data from a map file may be used as non-restart input, but this is only supported currently for
the legacy MapFormat = 1 (i.e., UGRID map files are not yet supported). Values are read in from
the map files as if they were samples, and further treated and interpolated as such. All interpolation
options from section D.4.2 can be used here. This option may be used as a non-exact restart state
when the model grid has been changed (e.g., locally refined or cropped to a subdomain).

D.4.6 Restart file

Restart files are discussed in section F.3.4. They should be included in your model in the MDU-file as
follows:
DR

[restart]
RestartFile = mdu_name_yyyymmdd_HHMMSS_rst.nc
RestartDateTime = # Restart time (YYYYMMDDHHMMSS), only relevant
# in case of restart from *_map.nc

Concerning parallel runs, each subdomain can generate its own restart/map file. To restart a parallel
run, one can use any of the following approaches:
⋄ On each subdomain use its own restart/map file, provided that the partition does not change. (This
means that in each partition MDU file specify its own restart/map file.)
⋄ Merge the subdomain restart/map files to one global file (see 8.4.4.2). This file enables to restart
a parallel run with a different or the same partition. (This means that specify the merged file for
all the partition MDU files.) One can also run a sequential simulation with this merged restart/map
file.

Deltares 465 of 562

 E Boundary conditions specification
Boundary conditions are part of the external forcing of a model and and as such declared in the
external-forcings file (section C.6).

E.1 Supported boundary types

E.1.1 Open boundaries

T
E.1.2 Astronomic boundary conditions
Boundary values can be specified for any location in terms of astronomical components in attribute files
with extension <cmp> (the BC-format, discussed furtheron, is supported as an alternative). Tidal mo-
tion are described as a series of simple harmonic constituent motions, each with its own characteristic
period:
AF H(t) = A0 +
k
X

i=1
Ai F (ci ) cos

2π
T (ci )
t + (V0 + u) (ci ) − Gi

(E.1)

in which:
ci i-th component, specified by label (name)
Ai amplitude of the i-th component
Gi phase of the i-th component

T (ci ) period
H(t) boundary value at time t
A0 constant offset value
DR

k number of relevant components

F (ci ) nodal amplitude factor
(V0 + u)(ci ) astronomical argument

The component (by label) ci , amplitude Ai and phase Gi for each component i are required in the
<cmp>-file In addition to the primary constituents, compound and higher harmonic constituents may
have to be used. This is the case in shallow water areas for example, where advection, large amplitude
to depth ratio, and bottom friction give rise to non-linear interactions.

F , V0 and u are also time-dependent. For a given period, their values are easily calculated or obtained
various tidal year books. V0 is a frequency dependent phase correction factor relating the local time
frame of the observations to an internationally agreed celestial time frame. Fi and ui are slowly varying
amplitude and phase corrections, The variations depend on the frequency, often with a cyclic period
of 18.6 years. By default, the nodal amplitude factors and astronomical arguments are re-calculated
every 6 hours.

E.1.3 Astronomic correction factors

For individual astronomic components, correcting factor αi for amplitude and offset δi may be specified
by the user so that the effective amplitude for that component becomes αi Ai and the effective phase
becomes Gi + δi .

E.1.4 Harmonic flow boundary conditions

Harmonic boundary conditions are specified in a manner similar to their astronomical counterpart,
except that the periods (first column of a .cmp file) are declared explicitly in minutes, rather than using
component names. Equation (E.1) applies with T (ci ) = Ti and furthermore F = 1 and (V0 + u) = 0.

Deltares 466 of 562

 Boundary conditions specification

E.1.5 QH-relation flow boundary conditions

In this type of boundary condition, a waterlevel is prescribed as a function of the integrated discharge
through a crossection defined by the polyline of the boundary.

The relation between waterlevel and discharge is specified in a lookup-table.

Within this table linear interpolation is applied.

Note that only one waterlevel is set for the entire QH-boundary, and that its behaviour is specified by a
single QH-table for the entire boundary.

T
E.1.6 Time-series flow boundary conditions
Time-series in the general time-series file format (section C.4) can be used to specify values on bound-
aries.
AF Boundary values are provided at discrete points in time, which are then used for interpolation at times
in between.

Extrapolation beyond the range of specified times is not supported, Time-series are also supported at
multiple vertical levels for quantities that are defined on layers (tracers, salinity, temperature, velocity).
These need to be specified in the BC-format (section E.2.3).

E.1.7 Time-series transport boundary conditions

The boundary conditions of tracers, salinity and temperature are specified similar to any other quantity
already mentioned. The quantity name should be in the form tracerbnd<name>, where name is
DR

the user-defined tracer name.

E.1.8 Time-series for the heat model parameters

In order to conduct a heat flux simulation (if in the MDU-file “Temperature” under [physics]
was set to 5), then four time-varying meteorological fields become relevant:
⋄ humidity (or dewpoint)
⋄ airtemperature
⋄ cloudiness
⋄ solar radiation

These are read as a three- or four-column vector (the first three variables of this list, either with or
without solar radiation). The corresponding quantity names in the <ext>-file are:
⋄ humidity_airtemperature_cloudiness
⋄ humidity_airtemperature_cloudiness_solarradiation
⋄ dewpoint_airtemperature_cloudiness
⋄ dewpoint_airtemperature_cloudiness_solarradiation

As for filetype, currently only the curvilinear format (C.13.2), the multicolumn time series (C.4) and
netCDF (C.13.4) are supported.

In the case of netCDF it is also possible to supply solarradiation as a separate quantity, and it
is possible to supply the term Qbr (see Eq.5.19) by the quantity longwaveradiation.

Deltares 467 of 562

 Boundary conditions specification

E.1.9 Time-series for varying air density

In the computation of the windstress, it is possible to use a spatial and/or time-varying air density. The
air density can be specified directly as a time-series or it can be computed from three other time-varying
meteorological fields:
⋄ airpressure
⋄ airtemperature
⋄ dewpoint

In order to compute it, option “computedAirdensity” under [wind] in the MDU-file must be

T
set to 1.

This option is only supported for netCDF. The quantity name in the <ext>-file is:
AF ⋄ airdensity

or, for computedAirdensity = 1 the three needed quantity names are:

⋄ airpressure
⋄ airtemperature
⋄ dewpoint

E.2 Boundary signal file formats

E.2.1 The <cmp> format

Warning:
⋄ The <cmp> format is a legacy file format without any metadata. It is recommended to use the
DR

<bc> format instead function=harmonic or astronomic (see Section C.5).

* comments
* ...
c[0] amplitude[0] phase[0]
c[1] amplitude[1] phase[1]
...

where c represents a period in minutes or the name of a valid astronomic component. Amplitudes are
assumed to be in the unit of the quantity.

E.2.2 The <qh> format

Warning:
⋄ The <qh> format is a legacy file format without any metadata. It is recommended to use the
<bc> format instead, with function=QHTable (see Section C.5).

* comments
* ...
discharge[0] waterlevel[0]
discharge[1] waterlevel[1]
...

E.2.3 The <bc> format

The external forcings file may point to this type of file via the forcingFile keyword (see sec-
tion C.6.2). The type of forcing is not restricted to boundary conditions, but may also contain meteo
time series (global or stations).

Deltares 468 of 562

 Boundary conditions specification

E.2.4 The netCDF-format

E.2.4.1 Scalar quantity for point-location time-series

The external forcings file may point to this type of file (for boundary condition support points) via the
forcingFile keyword (see section C.6.2).

NetCDF files that provide forcing data on point locations should meet the following structure:
⋄ The location labels have to be stored in a character variable with attribute cf_role = ’timeseries_id’.
This variable should have two dimensions, the primary being the series dimension and the sec-
ondary the string length dimension. The labels should always be unique.

T
⋄ The variable containing the timeseries data is identified by its attribute standard_name =
<quantity-name> and has two dimensions, the series dimension and the time dimension.
The latter can be the unlimited dimension.

In analogy with the ASCII BC-format (Section C.5), location label and quantity name uniquely identify
AF the timeseries.

Example header of a netCDF file with point data:

netcdf timeseries {
dimensions:
strlen = 7 ;
node = 3 ;
time = UNLIMITED ; // (18 currently)
variables:
DR

double time(time) ;
time:units = "hours since 2000-01-01 00:00:00" ;
char location(node, strlen) ;
location:cf_role = "timeseries_id" ;
double x(node) ;
x:axis = "x" ;
x:units = "km" ;
x:long_name = "x coordinate of projection" ;
x:standard_name = "projection_x_coordinate" ;
double y(node) ;
y:axis = "y" ;
y:units = "km" ;
y:long_name = "y coordinate of projection" ;
y:standard_name = "projection_y_coordinate" ;
double rainfall(time, node) ;
rainfall:long_name = "Rainfall" ;
rainfall:standard_name = "precipitation" ;
rainfall:units = "mm/day" ;
rainfall:_FillValue = "-999.9f" ;
data:

location =
"Station One",
"Station Two",
"Station Three" ;
}

E.2.4.2 Scalar Quantity for gridded data

The external forcings file may point to this type of file via the forcingFile keyword (see sec-
tion C.6.2).

Gridded data is used to apply per surface external forcing and should therefor spatially be 2D. There
are two different ways to supply this data: Either with a timeseries or a harmonic component.

Deltares 469 of 562

 Boundary conditions specification

E.2.4.2.1 timeseries
NetCDF files that provide forcing data on a grid with timeseries should meet the following structure:
⋄ The variable containing the timeseries data is identified by its attribute :standard_name =
<quantity-name> and has three dimensions, the time dimension and the grid coordinates. If
no suitable standard name is available, the modeller can provide a custom variable name in the
<*.ext> file using forcingVariableName=... (see section C.6.2.3).

Example header of a netCDF file with a gridded timeseries:

T
netcdf forcing_timeseries {
dimensions:
time = 8761 ;
x = 9 ;
y = 2 ;
variables:
AF double time(time) ;
time:time_origin = "2013-01-01 00:00:00" ;
time:long_name = "Time - minutes since 2013-01-01 00:00:00 +00:00" ;
time:standard_name = "time" ;
time:calender = "gregorian" ;
time:units = "minutes since 2013-01-01 00:00:00 +00:00" ;
double x(x) ;
x:standard_name = "longitude" ;
x:long_name = "longitude" ;
x:units = "degrees_east" ;
double y(y) ;
y:standard_name = "latitude" ;
y:long_name = "latitude" ;
DR

y:units = "degrees_north" ;
double air_pressure(time, y, x) ;
air_pressure:coordinates = "Time y x" ;
air_pressure:long_name = "Atmospheric Pressure" ;
air_pressure:standard_name = "air_pressure" ;
air_pressure:units = "Pa" ;
}

E.2.4.2.2 Harmonic component

When the external per surface forcing is periodic in nature, an alternate format can be used in which
the data is expressed in the form of a harmonic component. This form generally allows the forcing file
to be much smaller while it also provides flexibility in extrapolation.

NetCDF files that provide forcing data on a grid with a harmonic component should meet the following
structure:
⋄ The variable containing the amplitude data is identified by its attribute standard_name = <quantity-name>
and has two dimensions, the grid coordinates.
⋄ The phase offset is identified by the variable name phase and should have the same coordinate
dimensions as the amplitude data variable and phase:units = "deg".
⋄ The reference time for which the phase offset has been supplied should be defined a global at-
tribute named reference_time_of_component_phase.
⋄ The component’s period in seconds should be defined a global attribute named component_period_in_seconds.

When using this harmonic component format, the timeseries in each grid point i will be given by:
 
2π π
Hi (t) = Ai cos (t − tref ) − Gi (E.2)
T 180
in which:
Ai amplitude of the component at grid point i

Deltares 470 of 562

 Boundary conditions specification

T period of the component (seconds)

tref reference time of the component phase (seconds)
Gi phase of the component at grid point i (degrees)

Example header of a netCDF file with a gridded harmonic component:

netcdf forcing_component_s1 {
dimensions:
x = 9 ;
y = 2 ;
variables:

T
double x(x) ;
x:standard_name = "longitude" ;
x:long_name = "longitude" ;
x:units = "degrees_east" ;
double y(y) ;
y:standard_name = "latitude" ;
AF y:long_name = "latitude" ;
y:units = "degrees_north" ;
double amplitude(y, x) ;
amplitude:coordinates = "y x" ;
amplitude:long_name = "amplitude_of_airpressure" ;
amplitude:standard_name = "air_pressure" ;
amplitude:units = "Pa" ;
double phase(y, x) ;
phase:coordinates = "y x" ;
phase:long_name = "phase_of_component" ;
phase:standard_name = "phase" ;
phase:units = "deg" ;
DR

// global attributes:
:component = "S1" ;
:component_period_in_seconds = "86400" ;
:reference_time_of_component_phase = "2013-01-01 00:00:00 +00:00" ;
}

E.2.4.3 Vector quantity

NetCDF file can hold data for a vector quantity. For example, uxuyadvectionvelocitybnd boundary
condition has X and Y velocity components. To hold this vector quantity, NetCDF file has to have
an empty quantity with the name uxuyadvectionvelocitybnd in addition to scalar quantities for the
velocity components. This empty quantity has to have a string attribute named vector that contains
the vector element names: X and Y components. These names are separated by comma. The picture
below shows an example when the string contains quantities’ names ux and uy. As well the string can
contain standard and/or long names.

Remark:

Deltares 471 of 562

 Boundary conditions specification

⋄ Be sure that names in the string are not truncated due the string size.

T
AF
DR

Deltares 472 of 562

 F Output files
D-Flow FM can produce several types of output into several different files. This chapter summarizes
the types of output and how to configure them in them model definition. We distinguish five types of
output here:
1 The diagnostics file, a log file with live details of a single model run.
2 NetCDF output files for history, map and restart data.
3 Tecplot.
4 Timings file with performance statistics.
5 Shapefiles.

T
F.1 Diagnostics file
The diagnostics (dia) file is the log file of a single model simulation run. It is an important file to
check for warning or error messages, when suspecting a faulty model run. The filename is auto-
matically chosen as <mdu_name.dia>. For parallel model runs, each process writes its own file
AF <mdu_name_000X.dia>. The dia file has the following global structure:

Various INFO/DEBUG messages:

** INFO : Opened file : unstruc.hlp
[..]
The version of D-Flow FM used for this calculation:
* Deltares, D-Flow FM Version 1.1.145.41271M, Aug 11 2015, 18:05:31
Date and time of model run start:
File creation date: 18:27:44, 06-09-2015
[..]

Check for possible model initialization errors:

** WARNING: readMDUFile: [numerics] cflwavefrac=0.1 was in file, but not used.
DR

[..]

Upon successful initialization, a full printout of the effective model settings is given:
** INFO : ** Model initialization was successful **
** INFO : * Active Model definition:
# Generated on 18:27:45, 06-09-2015
# Deltares, D-Flow FM Version 1.1.145.41271M, Aug 11 2015, 18:05:31
[general]
[..]

Next, the time loop is started:

** INFO : **
** INFO : Writing initial output to file(s)...
** DEBUG : Opened netCDF file 'DFM_OUTPUT_035hammen/035hammen_his.nc' as #3.
** DEBUG : Opened netCDF file 'DFM_OUTPUT_035hammen/035hammen_map.nc' as #4.
** INFO : Done writing initial output to file(s).
[..]

Finishing summary of model run:

** INFO : simulation period (s) : 6400.0000000000
** INFO : nr of timesteps ( ) : 771.0000000000
** INFO : average timestep (s) : 8.3009079118
[..]
Some basic run time statistics
** INFO : time steps (s) : 76.2840000003
** INFO : Computation started at: 18:27:45, 06-09-2015
** INFO : Computation finished at: 18:29:04, 06-09-2015
** INFO :
Which parallellization options have been active in this run:
** INFO : MPI : no.
** INFO : OpenMP : yes.
#threads max : 8

F.2 Demanding output

The configuration of what output should be produced during a model run is via the MDU file, and
several attribute files for history files.

Deltares 473 of 562

 Output files

F.2.1 The MDU-file

The MDU-file has an [output]-section, with a range of key-value-pair options. See Table A.1 on
page 388 for all available output options. Enabling the various output files begins with setting the
output interval to a value > 0, see for example MapInterval and HisInterval in Table A.1.

F.2.2 Observation points

The observation point file defines the locations for time series output of flow "point" variables such as
water level and water depth. Observation points in 2D (or 3D) parts of the model domain are used to
monitor quantities at grid cell centres, and equivalently at the 1D grid points if the station is snapped to

T
a 1D grid point.

The keyword ObsFile should be used to point to the observation point file; optionally a space sepa-
rated list of files can be specified (see Appendix A).

Two types of observation point files are supported: <∗_obs.ini> files and old <∗.xyn> files. Both file
AF types are described in the subsections below; the first file type is recommended. The following general
remarks hold for both types of input:

Remarks:
⋄ The observation points are stationary by default.
⋄ Observation points may have non-unique names (also together with moving observation points),
but the results can only be distinguished by the column number in the output file, and this
practice is not advised.
⋄ In 2D/3D, the x,y -locations are snapped to the grid cell in which they lie. When an observation
point lies on a grid cell edge, snapping results are unpredictable.
⋄ In 1D, the observation point locations are snapped to the closest computational point; this may
DR

not always match the grid cell in which the point is located.
⋄ Time series are reported for the cell-centered solution data, that is: no interpolation to the exact
x,y -location takes place.

F.2.2.1 The observation point file with extension <∗_obs.ini>

This file can be used to define observation points in a more detailed way, amongst others in 1D using
(branchId, chainage), but see below for more possibilities.

Table F.1: Definition of observation points.

Keyword Type Default Description

[General]
fileVersion String 2.00 File version. Do not edit this.
fileType obsPoints File type. Do not edit this.
[ObservationPoint]
name String Name of the observation point (max. 255
characters).
locationType String 2d (optional) Only when x and y are also spec-
ified. 1d: snap to closest 1D grid point, 2d:
snap to closest 2D grid cell centre, all: snap
to closest 1D or 2D point.
branchId String (optional) Branch on which the observation
point is located.
chainage Double (optional) Location on the branch (m).
x Double (optional in 1D) x-coordinate of the location of
the observation point.
(continued on next page)

Deltares 474 of 562

 Output files

Keyword Type Default Description

(continued from previous page)
y Double (optional in 1D) y-coordinate of the location of
the observation point.
locationFile String (optional) Specifically for moving observation
points: name of a <∗.bc> containing the
timeseries for the x and y coordinates.

T
Remarks:
⋄ The station id/name may contain spaces, with no quoting needed.
⋄ If locationType = all then the observation point is first checked whether it lies inside a
2D grid cell. When this is not the case, in a second attempt it is snapped to the nearest 1D grid
point.
⋄ Three types of location specifications are available.
AF ⋄ When branchId is given, the keywords branchId and chainage will be used for the
location specification (only for 1D, the locationType is automatically assumed to be 1d).
⋄ When branchId is not given, but keywords x and y are, then these fixed coordinates will
be used. By default this is assumed to be a 2D/3D station location (i.e. locationType =
2d). Optionally, this location can be snapped to 1D calculation points using locationType
= 1d.
⋄ Finally, when only locationFile is given, that is considered to be a file with timeseries
for the x,y coordinates of a moving observation station.

Example:
DR

[General]
fileVersion = 2.00
fileType = obsPoints
[ObservationPoint]
name = ABDN
x = -2.06250000e+00
y = 5.71583333e+01
[ObservationPoint]
name = AVMH
x = -2.73750000e+00
y = 5.15083334e+01
[ObservationPoint]
name = #St Helier Jersey#
x = -2.11250000e+00
y = 4.91750000e+01
[ObservationPoint]
name = Obs4
branchId = Channel1
chainage = 275.0
[ObservationPoint]
name = Obs5
locationType = 1d
x = -2.31250000e+00
y = 5.01750000e+01

F.2.2.2 The observation point file with extension <∗.xyn>

The observation point file with extension <∗.xyn> is basically like a sample file (section C.3), but now
with station id strings in the third column:

-2.06250000e+00 5.71583333e+01 ABDN

-2.73750000e+00 5.15083334e+01 AVMH
-2.11250000e+00 4.91750000e+01 'St Helier Jersey'

Deltares 475 of 562

 Output files

Remarks:
⋄ The station id/name may contain spaces, in which case it should be surrounded by single
quotes, ’as follows’. Maximum length is 255 characters.
⋄ Each observation point is first checked whether it lies inside a 2D grid cell. When this is not the
case, in a second attempt it is snapped to the nearest 1D grid point.

F.2.3 Moving observation points

Moving observation points are specified via the <*_obs.ini>, using locationFile=example.bc
Below is an example of a <*.bc> file containing the moving point coordinates for a point with name =
ship1:

T
[Forcing]
name = ship1
function = timeseries
timeInterpolation = linear
AF quantity
unit
vector
quantity
=
=
=
=
time
minutes since 1992-08-31 00:00:00 +00:00
movingstationtxy:xCoordinate,yCoordinate
xCoordinate
unit = -
quantity = yCoordinate
unit = -
0 1140. 100.
1 1140. 50.
2 180. 50.
3 180. 100.
4 140. 100.
5 140. 50.
6 180. 50.
DR

7 180. 100.
8 140. 100.

Warning:
⋄ This example below describes deprecated functionality using the old external forcings format.
Use the new <*_obs.ini> file format instead, with keyword locationFile, see Section F.2.2.1.

Moving observation points are specified via the <∗.ext>-file:

QUANTITY=movingstationtxy
FILENAME=movingstation1.tim
FILETYPE=1
METHOD=1
OPERAND=O

The <∗.tim> file (one for each moving observation point) is a standard time series file (section C.4)
with three columns, containing the time in minutes since the reference data, the x- and y -position of
the moving station at that time.

Remarks:
⋄ Stationary and moving observation points form one large set of observation points in the output
his file.
⋄ No space or time interpolation is done: the reported values are instantaneous values for the grid
cell in which the moving observation point lies at that each output time.

Deltares 476 of 562

 Output files

F.2.4 Observation cross sections

Observation cross sections (or cross sections for short) define the location for time series output of
flow "flux" variables such as discharge and velocity. Other typical output quantities are instantaneous
as well as cumulative, space-integrated discharges and constituent transport. The keyword CrsFile
should be used to point to the observation cross section file; optionally a space separated list of files
can be specified (see Appendix A).

The location of an observation cross section can be specified using polylines using <∗_crs.pli> files.
The following general remarks hold for cross section input:

T
Remarks:
⋄ Observation cross sections may have non-unique names, but the results can only be distin-
guished by the column number in the output file, and this practice is not advised.
⋄ A cross section polyline is snapped to all grid cell edges (i.e., velocity points), whose flow link is
intersected by the polyline.
⋄ The flow data on velocity points is integrated along the polyline and across all vertical layers,
AF
F.2.4.1
resulting in a single time series per cross section and flow quantity.

Observation cross section file with extension <∗_crs.pli>

The format of the <∗_crs.pli> file is identical to that of a general polyline/polygon file (section C.2).

CrossSec1
4 2
132345.0 549030.0
132165.0 549285.0
131940.0 549550.0
DR

131820.0 549670.0
CrossSec2
3 2
131750.0 549865.0
131595.0 550025.0
131415.0 550175.0

Remarks:
⋄ The first header line of each polyline block contains the name of each cross section.
⋄ The cross section id/name may contain spaces, no quotes or other delimiters must be used.

F.3 NetCDF output files

All flow data output produced by D-Flow FM is written in the netCDF format. This cross-platform
storage format is widely used in the world. The contents of a file can be documented using variable
attributes and standardized meta data.

The following conventions are used in some of our output file types:
⋄ CF-conventions for both the timeseries (his) files and the spatial (map/class map/Fourier) files.
More information on: https://cfconventions.org/.
⋄ UGRID-conventions for the unstructured grids in the spatial (map/class map/Fourier) files. More
information on: http://ugrid-conventions.github.io/ugrid-conventions/.
⋄ ACDD-conventions for the geospatial and time bounds in the spatial (map/class map/Fourier) files.
More information on: https://wiki.esipfed.org/Category:Attribute_Conventions_Dataset_Discovery.

Spherical coordinates in NetCDF output files

The coordinate variables in all NetCDF output files are in the same coordinate system as the input grid
file (<_net.nc>). If this input file contains metadata describing grid mapping/coordinate transformation,
that metadata is also copied over into most output NetCDF files (specifically: into all UGRID-type
map/class map/Fourier files, and the history files). For models using a Cartesian/metric coordinate

Deltares 477 of 562

 Output files

system, an option is available to automatically add the equivalent latitude and longitude coordinate
values for all locations in the NetCDF output files. To enable this feature:
⋄ Verify that the input <_net.nc> file contains a grid mapping variable with coordinate transformation
parameters. In order to be found, the grid mapping variable should be called projected_coordinate_system,
or have the attribute :grid_mapping_name. Additionally, it must have an attribute :proj4_params
containing a PROJ-compatible coordinate transformation string1 .
⋄ If the input contains the above metadata, switch on the lat-lon conversion in the MDU file using
keyword [output] NcWriteLatLon = 1.

The fragment below shows an example of NetCDF output for a map file, where the input contained a

T
detailed grid mapping variable for UTM zone 32N:

netcdf example_map {
// [..]
variables:
AF int projected_coordinate_system ;
projected_coordinate_system:name = "ETRS89 / UTM zone 32N" ;
projected_coordinate_system:epsg = 25832 ;
projected_coordinate_system:grid_mapping_name = "transverse_mercator" ;
projected_coordinate_system:longitude_of_prime_meridian = 0. ;
projected_coordinate_system:semi_major_axis = 6378137. ;
projected_coordinate_system:semi_minor_axis = 6356752.31414036 ;
projected_coordinate_system:inverse_flattening = 298.257222101 ;
projected_coordinate_system:EPSG_code = "EPSG:25832" ;
projected_coordinate_system:value = "value is equal to EPSG code" ;
projected_coordinate_system:proj4_params =
"+proj=utm +zone=32 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs" ;
projected_coordinate_system:projection_name = "unknown" ;
projected_coordinate_system:wkt = "PROJCS[\"ETRS89 / UTM zone 32N\",\n",
" GEOGCS[\"ETRS89\",\n",
DR

" DATUM[\"European_Terrestrial_Reference_System_1989\",\n",
" SPHEROID[\"GRS 1980\",6378137,298.257222101,\n",
" AUTHORITY[\"EPSG\",\"7019\"]],\n",
" TOWGS84[0,0,0,0,0,0,0],\n",
" AUTHORITY[\"EPSG\",\"6258\"]],\n",
" PRIMEM[\"Greenwich\",0,\n",
" AUTHORITY[\"EPSG\",\"8901\"]],\n",
" UNIT[\"degree\",0.0174532925199433,\n",
" AUTHORITY[\"EPSG\",\"9122\"]],\n",
" AUTHORITY[\"EPSG\",\"4258\"]],\n",
" PROJECTION[\"Transverse_Mercator\"],\n",
" PARAMETER[\"latitude_of_origin\",0],\n",
" PARAMETER[\"central_meridian\",9],\n",
" PARAMETER[\"scale_factor\",0.9996],\n",
" PARAMETER[\"false_easting\",500000],\n",
" PARAMETER[\"false_northing\",0],\n",
" UNIT[\"metre\",1,\n",
" AUTHORITY[\"EPSG\",\"9001\"]],\n",
" AXIS[\"Easting\",EAST],\n",
" AXIS[\"Northing\",NORTH],\n",
" AUTHORITY[\"EPSG\",\"25832\"]]" ;
// [..]
double mesh2d_node_x(mesh2d_nNodes) ;
mesh2d_node_x:units = "m" ;
mesh2d_node_x:standard_name = "projection_x_coordinate" ;
mesh2d_node_x:long_name = "x-coordinate of mesh nodes" ;
double mesh2d_node_y(mesh2d_nNodes) ;
mesh2d_node_y:units = "m" ;
mesh2d_node_y:standard_name = "projection_y_coordinate" ;
mesh2d_node_y:long_name = "y-coordinate of mesh nodes" ;
double mesh2d_node_lon(mesh2d_nNodes) ;
mesh2d_node_lon:units = "degrees_east" ;
mesh2d_node_lon:standard_name = "longitude" ;
mesh2d_node_lon:long_name = "longitude coordinate of mesh nodes" ;
double mesh2d_node_lat(mesh2d_nNodes) ;
mesh2d_node_lat:units = "degrees_north" ;
mesh2d_node_lat:standard_name = "latitude" ;
mesh2d_node_lat:long_name = "latitude coordinate of mesh nodes" ;

1
https://proj.org/usage/projections.html

Deltares 478 of 562

 Output files

Detailed per NetCDF output file type

The following sections describe the specific details for each type of output file.

F.3.1 Timeseries as netCDF his-file

The history file <mdu_name_his.nc> contains the dimensions and variable definitions in its header,
followed by the actual data. For parallel runs, all data is gathered by domain #0 into <mdu_name_0000_his.nc>
(section 8.4.4).

T
F.3.1.1 Dimensions
The following dimensions are defined in a his file header:

netcdf weirfree_his {
AF dimensions:
time = UNLIMITED ; // (64 currently)
name_len = 64 ;
stations = 18 ;
cross_section = 4 ;
cross_section_name_len = 64 ;
cross_section_pts = 3 ;
npumps = 2 ;
// and possibly nweirgens, nweirs, ngategens, ngates, nsources/sinks

F.3.1.2 Location variables

The original location and IDs for stations, cross sections and sources/sinks are also included in the his
DR

file:

variables:
double station_x_coordinate(stations) ;
station_x_coordinate:units = "m" ;
station_x_coordinate:standard_name = "projection_x_coordinate" ;
station_x_coordinate:long_name = "x-coordinate" ;
double station_y_coordinate(stations) ;
station_y_coordinate:units = "m" ;
station_y_coordinate:standard_name = "projection_y_coordinate" ;
station_y_coordinate:long_name = "x-coordinate" ;
char station_name(stations, name_len) ;
station_name:cf_role = "timeseries_id" ;
station_name:long_name = "Observation station name" ;

double cross_section_x_coordinate(cross_section, cross_section_pts) ;

cross_section_x_coordinate:units = "m" ;
cross_section_x_coordinate:standard_name = "projection_x_coordinate" ;
cross_section_x_coordinate:long_name = "x-coordinate" ;
double cross_section_y_coordinate(cross_section, cross_section_pts) ;
cross_section_y_coordinate:units = "m" ;
cross_section_y_coordinate:standard_name = "projection_y_coordinate" ;
cross_section_y_coordinate:long_name = "y-coordinate" ;
char cross_section_name(cross_section, cross_section_name_len) ;

double source_sink_x_coordinate(source_sink, source_sink_pts) ;

source_sink_x_coordinate:units = "m" ;
source_sink_x_coordinate:standard_name = "projection_x_coordinate" ;
source_sink_x_coordinate:long_name = "x-coordinate" ;
double source_sink_y_coordinate(source_sink, source_sink_pts) ;
source_sink_y_coordinate:units = "m" ;
source_sink_y_coordinate:standard_name = "projection_y_coordinate" ;
source_sink_y_coordinate:long_name = "y-coordinate" ;
char source_sink_name(source_sink, source_sink_name_len) ;

Deltares 479 of 562

 Output files

F.3.1.3 Overview of output quantities in a netCDF his-file

An overview of output quantities in a his-file is given in Table F.2 and the following subsections. These
output quantities are present in the his-file only when the output object exists in the model. For ex-
ample, quantities on observation stations are present only when observation station(s) exists in the
model.

T
AF
DR

Deltares 480 of 562

 DR
Deltares

Table F.2: Global overview of output quantities in the history file.

Quantity name MDU keywords for output More information

Basic condition for his output HisInterval > 0 See Section F.2.1.
Quantities on observation stations. See section F.3.1.4.

A
Quantities on observation cross See section F.3.1.5.
sections.
Quantities on runup gauges.
Quantities on sources and sinks. wriHis_sourcesink > 0.

FT
Quantities for mass balance. wriHis_balance > 0. See section F.3.1.6.
Quantities on hydraulic structures. See section F.3.1.8.
Quantities on laterals. wriHis_lateral > 0. See ??.
Quantities for dredging and dumping. [sediment] DredgeFile is specified.
Quantities for checkerboard monitor. [numerics] checkerboardmonitor = 1.
time Instant time.
timestep Latest computational timestep size in each
output interval [s].

Output files
481 of 562
 Output files

F.3.1.4 Variables on stations

Variables on observations station are typically defined as follows:

double waterlevel(time, stations) ;

waterlevel:standard_name = "sea_surface_level" ;
waterlevel:long_name = "Water level" ;
waterlevel:units = "m" ;
waterlevel:coordinates = "station_x_coordinate station_y_coordinate station_name" ;
waterlevel:_FillValue = -999. ;

T
Output for observation stations is available as time series in the history file. The output is shown in
history file when one or more observation stations are defined in the model. The available output
quantities are listed in Table F.3. These output variables are quantities locating on the observation
stations. Such output can be switched on/off by setting value 1/0, respectively, to MDU [output]
keywords, as listed in the third column of Table F.3 (More details about these MDU keywords refer to
AF Table A.1.) If for one variable there is no MDU keyword shown in the third column, then the output of
this variable is always switched on.
DR

Deltares 482 of 562

 DR
Deltares

Table F.3: Output quantities of observation stations in history file.

Quantity name Description [Unit] MDU [output] keyword to switch on/off

this output
station_id Identification string of the observation stations.

A
station_name Names of the observation stations.
station_x_coordinate Original x-coordinates of stations (non-snapped) [m].
station_y_coordinate Original y-coordinates of stations (non-snapped) [m].
# The following variables are only for 3D models:

FT
zcoordinate_c Vertical coordinate at center of flow element and layer [m]. wriHis_zcor (default=1)
zcoordinate_w Vertical coordinate at centre of flow element and at layer interface [m]. wriHis_zcor (default=1)
zcoordinate_wu Vertical coordinate at edge of flow element and at layer interface [m]. wriHis_zcor (default=1)
# The above variables are only for 3D models.
station_geom Geometry variables, see Section F.3.1.9.
# End of time-independent variables.
waterlevel Water level [m]. wriHis_waterlevel_s1 (default=1)
bedlevel Bottom level [m]. wriHis_bedlevel (default=1)
waterdepth Water depth [m]. wriHis_waterdepth (default=0)
tausx, tausy x-, y-components of mean bottom shear stress vector [Pa]. wriHis_taucurrent (default=1)
x_velocity, y_velocity x-, y-components of flow element center velocity vector [m/s]. wriHis_velocity_vector (default=1)
# Following are only for 3D models:
z_velocity z-component of flow element center velocity vector [m/s]. wriHis_velocity_vector (default=1)
depth-averaged_x_velocity, x-, y-components of flow element depth-averaged center velocity vector [m/s]. wriHis_velocity_vector (default=1)
depth-averaged_y_velocity
tke Turbulent kinetic energy [m2 /s2 ] when MDU keyword wriHis_turbulence (default=1)
[numerics] Turbulencemodel >= 3.
vicww Turbulent vertical eddy viscosity [m2 /s] when MDU keyword wriHis_turbulence (default=1)

Output files
[numerics] Turbulencemodel > 1.
483 of 562

eps Turbulent energy dissipation [m2 /s3 ] when MDU keyword wriHis_turbulence (default=1)
[numerics] Turbulencemodel = 3.
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name Description MDU [output] keyword to switch on/off
this output
tau Turbulent time scale [1/s] when MDU keyword [numerics] Turbulencemodel = 4. wriHis_turbulence (default=1)
rich Richardson Nr [-]. Richardsononoutput (default=0)

A
# The above are only for 3D models.
salinity Salinity [ppt] when MDU keyword [physics] Salinity > 0. wriHis_salinity (default=1)
velocity_magnitude Velocity magnitude [m/s]. Or Eulerian velocity magnitude [m/s] when MDU keyword wriHis_velocity (default=1)
[output] EulerVelocities equals 1.

FT
discharge_magnitude Average discharge magnitude [m3 /s]. wriHis_discharge (default=1)
2
R Roller energy per square meter [J/m ] when MDU keyword [waves] Wavemodelnr = 4.
# The following variables are for models when MDU keyword [waves] Wavemodelnr > 0:
hwav Significant wave height [m]. Or root mean square wave height based on wave energy [m] when wriHis_waves (default=1)
MDU keyword [waves] jahissigwav = 0.
twav Wave period [s]. wriHis_waves (default=1)
phiwav Wave from direction [deg from N]. wriHis_waves (default=1)
rlabda Wave length [m]. wriHis_waves (default=1)
uorb Orbital velocity [m/s]. wriHis_waves (default=1)
ustokes, vstokes x-, y-components of Stokes drift [m/s]. wriHis_waves (default=1)
# The above variables are for models when MDU keyword [waves] Wavemodelnr > 0.
wtau Mean bed shear stress [Pa]. wriHis_taucurrent (default=1)
# The following variables are for models with temperature:
temperature Temperature [◦ C] when MDU keyword [physics] Temperature > 0. wriHis_temperature (default=1)
wind Wind speed [m/s] when MDU keyword [physics] Temperature > 1. wriHis_temperature and
wriHis_heat_fluxes (default=1)
Tair Air temperature [◦ C] when MDU keyword [physics] Temperature > 1. wriHis_temperature and
wriHis_heat_fluxes (default=1)

Output files
rhum Relative humidity [-] when MDU keyword [physics] Temperature = 5. wriHis_temperature and
484 of 562

wriHis_heat_fluxes (default=1)
clou Cloudiness [-] when MDU keyword [physics] Temperature = 5. wriHis_temperature and
wriHis_heat_fluxes (default=1)
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name Description MDU [output] keyword to switch on/off
this output
Qsun Solar influx [W/m2 ] when MDU keyword [physics] Temperature = 5. wriHis_temperature and
wriHis_heat_fluxes (default=1)

A
Qeva Evaporative heat flux [W/m2 ] when MDU keyword [physics] Temperature = 5. wriHis_temperature and
wriHis_heat_fluxes (default=1)
Qcon Sensible heat flux [W/m2 ] when MDU keyword [physics] Temperature = 5. wriHis_temperature and
wriHis_heat_fluxes (default=1)

FT
Qlong Long wave back radiation [W/m2 ] when MDU keyword [physics] Temperature = 5. wriHis_temperature and
wriHis_heat_fluxes (default=1)
Qfreva Free convection evaporative heat flux [W/m2 ] when MDU keyword wriHis_temperature and
[physics] Temperature = 5. wriHis_heat_fluxes (default=1)
Qfrcon Free convection sensible heat flux [W/m2 ] when MDU keyword wriHis_temperature and
[physics] Temperature = 5. wriHis_heat_fluxes (default=1)
Qtot Total heat flux [W/m2 ] when MDU keyword [physics] Temperature > 1. wriHis_temperature and
wriHis_heat_fluxes (default=1)
# The above variables are for models with temperature.
density Density [kg/m3 ] when MDU keyword [physics] Temperature or wriHis_density (default=1)
[physics] Salinity or [sediment] Sedimentmodelnr is larger than 0.
Names of all constituents All constituents [unit depends] when there is at least one constituent. wriHis_constituents (default=1)
Names of all water quality bottom All water quality bottom variables [unit depends] when there is at least one water quality bottom wriHis_wqBot (default=1)
variables variable.
Names of all water quality bottom All water quality bottom variables [unit depends] when there is at least one water quality bottom wriHis_wqBot3d (default=0)
variables with suffix _3D variable.
water_quality_output_j, Water quality output (from 1 to number of user outputs) [unit depends] when water quality
j=1,...,noout_user process is either substances initiated or processes activated.
water_quality_stat_j, Water quality statistic variables (from 1 to number of statistic outputs) [unit depends] when water
j=1,...,noout_statt quality process is either substances initiated or processes activated.

Output files
# The following are sediment transport variables:
485 of 562

# for model when both MDU keywords [sediment] SedFile and MorFile are not empty, and Sedimentmodelnr is 4.
sedfrac_name Sediment fraction identifier [-] when the computed first sediment fraction is positive. wriHis_sediment (default=1)
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name Description MDU [output] keyword to switch on/off
this output
seddif (Only for 3D models) sediment vertical diffusion [m2 /s] when the computed first sediment fraction wriHis_sediment (default=1)
is positive.

A
sed Sediment concentration [kg/m3 ] when the computed first sediment fraction is positive. wriHis_sediment (default=1)
ws Sediment settling velocity [m/s] when the computed first sediment fraction is positive. wriHis_sediment (default=1)
taub Bed shear stress for morphology [Pa] when MDU keywords wriHis_sediment (default=1)
[sediment] Sedimentmodelnr is positive, and MorFile keyword [Output] taub is

FT
true.
sbcx, sbcy x-, y-components of current related bedload transport, with unit [kg/s/m] if MorFile keyword wriHis_sediment (default=1)
[Output] TranspType = 0, or [m3 /s/m] if MorFile keyword
[Output] TranspType = 1 or 2. Output of these variables is available when MDU
keywords Sedimentmodelnr is positive, and MorFile keyword
[Output] BedTranspDueToCurrentsAtZeta is true.
sbwx, sbwy x-, y-components of wave related bedload transport, with unit [kg/s/m] if MorFile keyword wriHis_sediment (default=1)
[Output] TranspType = 0, or [m3 /s/m] if MorFile keyword
[Output] TranspType = 1 or 2. Output of these variables is available when MorFile
keyword [Output] BedTranspDueToWavesAtZeta is true, and MDU keywords
[waves] Wavemodelnr > 0, and [waves] flowWithoutWaves is false.
sswx, sswy x-, y-components of wave related suspended transport, with unit [kg/s/m] if MorFile keyword wriHis_sediment (default=1)
[Output] TranspType = 0, or [m3 /s/m] if MorFile keyword
[Output] TranspType = 1 or 2. Output of these variables is available when MorFile
keyword [Output] SuspTranspDueToWavesAtZeta is true, and MDU keywords
[waves] Wavemodelnr > 0, and [waves] flowWithoutWaves is false.
sscx, sscy x-, y-components of current related suspended transport, with unit [kg/s/m] if MorFile keyword wriHis_sediment (default=1)
[Output] TranspType = 0, or [m3 /s/m] if MorFile keyword
[Output] TranspType = 1 or 2. Output of these variables is available when when
MorFile keyword [Output] SuspTranspDueToCurrentsAtZeta is true.
sourse Source aterm suspended sediment transport [kg/m3 /s], when MorFile keyword wriHis_sediment (default=1)
[Output] SourceSinkTerms is true.

Output files
sinkse Sink term suspended sediment transport [1/s], when MorFile keyword wriHis_sediment (default=1)
486 of 562

[Output] SourceSinkTerms is true.

bodsed Available sediment mass in the bed [kg/m2 ], when MorFile keyword wriHis_sediment (default=1)
[Underlayer] IUnderLyr = 1.
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name Description MDU [output] keyword to switch on/off
this output
dpsed Sediment thickness in the bed [m], when MorFile keyword [Underlayer] IUnderLyr = 1. wriHis_sediment (default=1)
msed Available sediment mass in a layer of the bed [kg/m2 ], when MorFile keyword wriHis_sediment (default=1)

A
[Underlayer] IUnderLyr = 2.
thlyr Thickness of a layer of the bed [m], when MorFile keyword wriHis_sediment (default=1)
[Underlayer] IUnderLyr = 2.
poros Porosity of a layer of the bed [-], when MorFile keywords [Underlayer] IUnderLyr = 2 wriHis_sediment (default=1)

FT
and [Underlayer] IPorosity > 0.
lyrfrac Volume fraction in a layer of the bed [m], when MorFile keyword wriHis_sediment (default=1)
[Underlayer] IUnderLyr = 2.
frac Availability fraction in top layer [-], when MorFile keyword [output] frac is true. wriHis_sediment (default=1)
mudfrac Mud fraction in top layer [-], when MorFile keyword [output] MudFrac is true. wriHis_sediment (default=1)
sandfrac Sand fraction in top layer [-], when MorFile keyword [output] SandFrac is true. wriHis_sediment (default=1)
fixfac Reduction factor due to limited sediment thickness [-], when MorFile keyword wriHis_sediment (default=1)
[output] FixFac is true.
hidexp Hiding and exposure factor [-], when MorFile keyword [output] HidExp is true. wriHis_sediment (default=1)
mfluff Sediment mass in fluff layer [-], when MorFile keyword [FluffLayer] Type > 0 and wriHis_sediment (default=1)
number of suspended sediment fractions is positive.
# The above are sediment transport variables.
# for model when both MDU keywords [sediment] SedFile and MorFile are not empty, and Sedimentmodelnr is 4.
sediment_concentration Sediment concentration [kg/m3 ], when MDU keywords [waves] Wavemodelnr > 0 and, wriHis_sediment (default=1)
either MDU keywords [sediment] SedFile or MorFile is empty or Sedimentmodelnr
is not 4.
# Variables for wind models
patm Atmospheric pressure [N/m2 ], when atmospheric pressure is provided via the EXT file, for wriHis_wind (default=1)
example with quantity airpressure_windx_windy (see Table C.9).
windx, windy x-, y-components of the wind vector [m/s], when wind is provided via the EXT file, for example wriHis_wind (default=1)

Output files
487 of 562

with quantity airpressure_windx_windy (see Table C.9), or when

[external forcing] WindExt > 0.
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name Description MDU [output] keyword to switch on/off
this output
rain Precipitation rate [mm/day], when rainfall is provided via the EXT file, for example with quantity wriHis_rain (default=1)
rainfall_rate (see Table C.9), or when MDU keyword

A
[external forcing] Rainfall > 0.
infiltration_cap, Infiltration capacity and actual infiltration rate [mm/hr], respectively. Output of these variables are wriHis_infiltration (default=1)
infiltration_actual available when MDU keyword [grw] Infiltrationmodel = 2 or 4.

FT

Output files
488 of 562
 Output files

F.3.1.5 Variables on cross sections

Variables on cross sections are typically defined as follows:

double cross_section_discharge(time, cross_section) ;

cross_section_discharge:units = "m3 s-1" ;
cross_section_discharge:coordinates = "cross_section_name" ;

Output on cross sections is available as time series in the history file. The output is only included
when one or more cross sections are defined in the model. The available output quantities are listed

T
in Table F.4. These output variables are quantities located on the cross sections. Output of these
variables is always switched on.
AF
DR

Deltares 489 of 562

 DR
Deltares

Table F.4: Output quantities on cross sections in history file.

Quantity name Description [Unit]

cross_section_name Names of cross sections [-].
cross_section_geom Geometry variables, see Section F.3.1.9

A
# End of time-independent variables.
cross_section_discharge Discharge through cross sections [m3 /s].
cross_section_cumulative_discharge Cumulative discharge through cross sections [m3 ]
cross_section_area Area of cross sections [m2 ]

FT
cross_section_velocity Averaged velocity (by area) through cross sections [m/s].
# The following variables are for transport models,
cross_section_cumulative_⟨name of constituent⟩ Cumulative flux (based on upwind flow cell) for each constituent. If the constituent
is sediment, then the unit is [kg] when MorFile keyword
[output] TranspType is 0, and is [m3 ] when this keyword is 1 or 2. For
non-sediment constituent, the unit is [constituent unit m3 ] where [constituent unit]
is specified by users, if it is not specified, then the unit is [-].
cross_section_⟨name of constituent⟩ Flux (based on upwind flow cell) for each constituent. If the constituent is
sediment, then the unit is [kg/s] when MorFile keyword
[output] TranspType is 0, and is [m3 /s] when this keyword is 1 or 2. For
non-sediment constituent, the unit is [constituent unit m3 /s] where [constituent
unit] is specified by users, if it is not specified, then the unit is [-].
# The above variables are for transport models.
# The following variables are for sediment models,
# when MDU keyword [sediment] Sedimentmodelnr = 4 and number of sediment tractions is positive.
cross_section_bedload_sediment_transport Cumulative bed load sediment transport [kg].
cross_section_suspended_sediment_transport Cumulative suspended load sediment transport [kg], when number of suspended
sediment fractions is positive.
cross_section_bedload_sediment_transport_⟨name of sediment fraction⟩ cumulative bed load sediment transport per fraction [kg]

Output files
490 of 562
 Output files

F.3.1.6 Mass balance output

The history file may also contain model-global, time-integrated mass balance output, for example:

double WaterBalance_total_volume(time) ;
WaterBalance_total_volume:units = "m3" ;

The available output quantities are listed in Table F.5. Output of these variables is switched on or off by
setting MDU keyword [output] wriHis_balance = 1 or 0, respectively (default is 1).

T
AF
DR

Deltares 491 of 562

 DR
Deltares

Table F.5: Output quantities for the mass balance in history file.

Quantity name Description [Unit]

water_balance_total_volume Total volume at the end of timestep. [m3 ]
water_balance_storage Net storage since Tstart. [m3 ]

A
water_balance_volume_error Volume error since Tstart [m3 ]
water_balance_boundaries_in Cumulative inflow through boundaries since Tstart. [m3 ]
water_balance_boundaries_out Cumulative outflow through boundaries since Tstart. [m3 ]
water_balance_boundaries_total Net inflow through boundaries since Tstart. [m3 ]

FT
water_balance_exchange_with_1D_in Cumulative inflow via SOBEK–D-Flow FM 1D–2D boundaries since Tstart. [m3 ]
water_balance_exchange_with_1D_out Cumulative outflow via SOBEK–D-Flow FM 1D–2D boundaries since Tstart. [m3 ]
water_balance_exchange_with_1D_total Net inflow via SOBEK–D-Flow FM 1D–2D boundaries since Tstart. [m3 ]
water_balance_precipitation_total Total precipitation volume since Tstart. [m3 ]
water_balance_evaporation Evaporation. [m3 ]
water_balance_source_sink Net inflow via source–sink elements since Tstart. [m3 ]
InternalTidesDissipation Total internal tides dissipation, when internaltidesfrictioncoefficient in [TJ].
EXT file is specified.
Gravitational_Input Total Gravitational Input (incl. SAL), when MDU keyword [TJ]
[physics] TidalForcing = 1.
SAL_Input Total input of self attraction and loading, when MDU keyword [TJ]
[physics] SelfAttractionLoading > 0.
SAL_Input_2 Total input of self attraction and loading with different formulation, when MDU keyword [TJ]
[physics] SelfAttractionLoading > 0.
water_balance_groundwater_in Cumulative volume received from groundwater. [m3 ]
water_balance_groundwater_out Cumulative volume out towards groundwater. [m3 ]
water_balance_groundwater_total Total net inflowing volume from groundwater. [m3 ]
water_balance_laterals_in Cumulative inflowing volume through laterals since Tstart. [m3 ]
water_balance_laterals_out Cumulative outflowing volume through laterals since Tstart. [m3 ]

Output files
492 of 562

water_balance_laterals_total Total net inflowing volume through laterals since Tstart. [m3 ]
water_balance_laterals_in_1D Cumulative inflowing volume through 1D-laterals since Tstart. [m3 ]
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name Description [Unit]
water_balance_laterals_out_1D Cumulative outflowing volume through 1D-laterals since Tstart. [m3 ]
water_balance_laterals_total_1D Total net inflowing volume through 1D-laterals since Tstart. [m3 ]
water_balance_laterals_in_2D Cumulative inflowing volume through 2D-laterals since Tstart. [m3 ]

A
water_balance_laterals_out_2D Cumulative outflowing volume through 2D-laterals since Tstart. [m3 ]
water_balance_laterals_total_2D Total net inflowing volume through 2D-laterals since Tstart. [m3 ]
water_balance_Qext_in Cumulative inflowing volume through external discharge since Tstart. [m3 ]

FT
water_balance_Qext_out Cumulative outflowing volume through external discharge since Tstart. [m3 ]
water_balance_Qext_total Total net inflowing volume through external discharge since Tstart. [m3 ]
water_balance_Qext_in_1D Cumulative inflowing volume through 1D external discharge since Tstart. [m3 ]
water_balance_Qext_out_1D Cumulative outflowing volume through 1D external discharge since Tstart. [m3 ]
water_balance_Qext_total_1D Total net inflowing volume through 1D external discharge since Tstart. [m3 ]
water_balance_Qext_in_2D Cumulative inflowing volume through 2D external discharge since Tstart. [m3 ]
water_balance_Qext_out_2D Cumulative outflowing volume through 2D external discharge since Tstart. [m3 ]
water_balance_Qext_total_2D Total net inflowing volume through 2D external discharge since Tstart. [m3 ]
water_balance_total_volume_interception Total volume of the interception layer at the end of timestep. [m3 ]
water_balance_evaporation_interception Total evaporated volume from interception layer since Tstart. [m3 ]
water_balance_precipitation_on_ground Total volume of rain fallen onto the ground (i.e., not intercepted) since Tstart. [m3 ]

Output files
493 of 562
 Output files

F.3.1.7 Variables on sources/sinks

Variables on sources/sinks are typically defined as follows:

double source_sink_prescribed_discharge(time, source_sink) ;

source_sink_prescribed_discharge:units = "m3 s-1" ;
source_sink_prescribed_discharge:coordinates = "source_sink_name" ;

Other quantities that can be written are:

T
⋄ source sink prescribed salinity increment;
⋄ source sink prescribed temperature increment;
⋄ source sink current discharge;
⋄ source sink cumulative volume;
⋄ source sink discharge average;
⋄ geometry variables, see Section F.3.1.9.
AF These variables are automatically written to his-file if any source/sink exists. One can switch it off by
setting in MDU-file that [output] wriHis_sourcesink = 0.

F.3.1.8 Hydraulic structure output

A history file can also contain automatic output for hydraulic structures, without the need to add an
explicit cross section at the same location. An example variable is:

double weirgen_discharge(time, weirgens) ;

DR

weirgen_discharge:long_name = "Discharge through weir" ;

Other quantities that can be written are:

⋄ weir crest level at current time;
⋄ Total discharge through gate at current time;
⋄ gate sill level at current time;
⋄ gate sill width at current time;
⋄ gate door lower edge level at current time;
⋄ gate door opening width at current time;
⋄ Total pump discharge at current time;
⋄ Max. pump capacity at current time;
⋄ Geometry variables, see Section F.3.1.9.

Quantities for different hydraulic structures are described in the following subsections.

F.3.1.8.1 Pump
Output for pump structures is available as time series in the history file. The output can be switched on
or off using the MDU setting [output] wriHis_structure_pump (cf. Table A.1). The available
output quantities are listed in Table F.6.

Table F.6: Output quantities of pumps in history file.

Quantity name Description Unit

pump_id Id of the pump.
(continued on next page)

Deltares 494 of 562

 Output files

Quantity name Description Unit

(continued from previous page)
pump_xmid, pump_ymid x- and y-coordinates of representative mid [m]
point of the pump location (snapped polyline).
pump_structure_discharge∗ Discharge through the pump. [m3 /s]
pump_capacity Prescribed capacity of the pump. [m3 /s]
∗
pump_discharge_dir Discharge w.r.t. pump orientation. [m3 /s]
pump_s1up Water level at upstream of the pump. [m AD]
pump_s1dn Water level at downstream of the pump. [m AD]

T
pump_s1_delivery_side Water level at delivery side of pump. [m AD]
pump_s1_suction_side Water level at suction side of pump. [m AD]
pump_structure_head Head difference across the pump structure, [m]
this is computed by pump_s1up subtracting
AF pump_head
pump_s1dn.
Head difference in pumping direction, this is
computed by pump_s1_delivery_side
subtracting pump_s1_suction_side.
[m]

pump_actual_stage Actual stage of the pump. It gives valid values

only when number of stages is larger than 0.
pump_reduction_factor Reduction factor of the pump.

Remarks:
⋄ Variables with notation ∗ show a fill value (-999) if the flow link is dry. When the pump covers
DR

more than one flow link, variable pump_structure_discharge is summed across all wet
links.
⋄ pump_s1up shows a fill value (-999) when the upstream cell is dry. If there is more than one
upstream cell, then the value is a weighted average, with the weights being the widths of the flow
links whose corresponding upstream cells are wet. This also applies to pump_s1dn consider-
ing downstream cells. Moreover, pump_s1_delivery_side/pump_s1_suction_side
also follows the similar rule, depending on if its delivery/suction side is wet or not, respectively.
⋄ pump_structure_head and pump_head have a valid value only when both sides are wet.
Otherwise it shows a fill value (-999). In the situation when there is more than one upstream/-
downstream cell, the value is a weighted average, with the weights being the widths of the flow
links whose corresponding upstream and downstream cells are both wet.
⋄ The pump_capacity does not include any reduction factor yet. The actual discharge is avail-
able in pump_discharge_dir and only this variable includes a possible reduction factor, as
well as volume-based relaxation (cf. Section 12.11.6).

F.3.1.8.2 General structure

Output for general structures is available as time series in the history file. The output can be switched
on or off using the MDU setting [output] wriHis_structure_gen (cf. Table A.1). The avail-
able output quantities are listed in Table F.7.

Table F.7: Output quantities of general structures in history file.

Quantity name Description Unit

general_structure_id Id of the general structure.
general_structure_discharge∗ Total discharge through the general structure. [m3 /s]
general_structure_crest_level Actual crest level that is used in the computation. [m AD]
general_structure_crest_width Actual crest width that is used in the computation. [m]
(continued on next page)

Deltares 495 of 562

 Output files

Quantity name Description Unit

(continued from previous page)
general_structure_gate_lower_edge_ Actual gate lower edge level that is used in the com- [m AD]
level putation.
general_structure_gate_opening_ Actual gate opening width that is used in the compu- [m]
width tation.
general_structure_s1up Water level at upstream of the general structure. [m AD]
general_structure_s1dn Water level at downstream of the general structure. [m AD]
general_structure_discharge_ Discharge through gate opening. [m3 /s]

T
through_gate_opening∗
general_structure_discharge_ Discharge over gate. [m3 /s]
over_gate∗
general_structure_discharge_ Discharge under gate. [m3 /s]
under_gate∗
AF
general_structure_gate_opening_
height
general_structure_gate_upper_edge_ Gate upper edge level.
Gate opening height. [m]

[m AD]
level
general_structure_head Head difference across the general structure. [m]
general_structure_velocity_ Velocity through gate opening. [m/s]
through_gate_opening∗
general_structure_velocity_ Velocity over gate. [m/s]
over_gate∗
general_structure_velocity_ Velocity under gate. [m/s]
DR

under_ gate∗
general_structure_flow_area∗ Total flow area. [m2 ]
general_structure_flow_area_in_ Flow area in gate opening. [m2 ]
gate_opening∗
general_structure_flow_area_ Flow area over gate. [m2 ]
over_gate∗
general_structure_flow_area_ Flow area under gate. [m2 ]
under_gate∗
general_structure_state∗ Flow state through the general structure. Possible
values:
⋄ 0: No flow
⋄ 1: free weir flow
⋄ 2: submerged weir flow
⋄ 3: free gate flow
⋄ 4: submerged gate flow
general_structure_s1_on_crest∗ Water level on crest. [m AD]
∗
general_structure_velocity Average velocity through the general structure. [m/s]
∗
general_structure_force_difference Force difference per unit width at the general struc- [N/m]
ture.

Remarks:
⋄ Variables with notation ∗ show a fill value (-999) if the flow link is dry. When the general structure
covers more than one flow link, the written variables are either summed across all wet links (e.g.
discharges and areas), or a weighted average, with the weights being the widths of the wet flow
links (e.g. water level on crest and force difference per unit width). Specially, velocity is the
summed discharge divided by the summed area on wet links.
⋄ general_structure_s1up shows a fill value (-999) when the upstream cell is dry. If there
is more than one upstream cell, then the value is a weighted average, with the weights being

Deltares 496 of 562

 Output files

the widths of the flow links whose corresponding upstream cells are wet. This also applies to
general_structure_s1dn considering downstream cells.
⋄ general_structure_head has a valid value only when both upstream and downstream
cells are wet. Otherwise it shows a fill value (-999). This means that, when the upstream cell
is dry while downstream cell is wet, general_structure_head has a fill value (-999). In
the situation when there is more than one upstream/downstream cell, the value is a weighted
average, with the weights being the widths of the flow links whose corresponding upstream and
downstream cells are both wet.
⋄ general_structure_state shows a fill value (-999) if the flow link is dry.
If the flow link is wet, on this flow link, three states of the flow are computed: state of flow under
gate, state of flow between gate and state of flow over gate. The maximal value of these integers

T
will be used as the flow state of the link. When the general structure covers more than one flow
link, then the state may differ per flow link. If not all of the flow links have the same state value,
the state is written to file as a fill value (-999).

F.3.1.8.3 Weir
AF Output for weir structures is available as time series in the history file. The output can be switched on
or off using the MDU setting [output] wriHis_structure_weir (cf. Table A.1). The available
output quantities are listed in Table F.8.

Table F.8: Output quantities of weirs in history file.

Quantity name Description Unit

weirgen_id Id of the weir.
∗
weirgen_discharge Discharge through the weir. [m3 /s]
weirgen_crest_level Actual crest level that is used in the computa- [m AD]
DR

tion.
weirgen_crest_width Actual crest width that is used in the compu- [m]
tation.
weirgen_s1up Water level at upstream of the weir. [m AD]
weirgen_s1dn Water level at downstream of the weir. [m AD]
weirgen_structure_head Head difference across the weir. [m]
∗
weirgen_flow_area Flow area at the weir. [m2 ]
weirgen_velocity∗ Velocity through the weir. [m/s]
∗
weirgen_state Flow state at the weir. Possible values:
⋄ 0: No flow
⋄ 1: free weir flow
⋄ 2: submerged weir flow
weirgen_force_difference∗ Force difference per unit width at the weir. [N/m]
∗
weirgen_s1_on_crest Water level on crest of the weir. [m AD]

Remarks:
⋄ Variables with notation ∗ show a fill value (-999) if the flow link is dry. When the weir covers more
than one flow link, the written variables are either summed across all wet links (e.g. discharge
and area), or a weighted average, with the weights being the widths of the wet flow links (e.g.
water level on crest and force difference per unit width). Specially, velocity is the summed
discharge divided by the summed area on wet links.
⋄ weirgen_s1up shows a fill value (-999) when the upstream cell is dry. If there is more than
one upstream cell, then the value is a weighted average, with the weights being the widths of the
flow links whose corresponding upstream cells are wet. This also applies to weirgen_s1dn
considering downstream cells.
⋄ weirgen_structure_head has a valid value only when both upstream and downstream
cells are wet. Otherwise it shows a fill value (-999). This means that, when the upstream cell

Deltares 497 of 562

 Output files

is dry while downstream cell is wet, weirgen_structure_head has a fill value (-999). In
the situation when there is more than one upstream/downstream cell, the value is a weighted
average, with the weights being the widths of the flow links whose corresponding upstream and
downstream cells are both wet.
⋄ weirgen_state shows a fill value (-999) if the flow link is dry. When the weir covers more
than one wet flow link, then the state may differ per flow link. If not all of the flow links have the
same state value, the state is written to file as a fill value (-999).

F.3.1.8.4 Orifice
Output for orifice structures is available as time series in the history file. The output can be switched

T
on or off using the MDU setting [output] wriHis_structure_orifice (cf. Table A.1). The
available output quantities are listed in Table F.9.

AF Table F.9: Output quantities of orifices in history file.

Quantity name Description Unit

orifice_id Id of the orifice.
orifice_discharge∗ Discharge through the orifice. [m3 /s]
orifice_crest_level Actual crest level that is used in the computa- [m AD]
tion.
orifice_crest_width Actual crest width that is used in the compu- [m]
tation.
orifice_gate_lower_edge_ Actual gate lower edge level that is used in the [m AD]
level computation.
orifice_s1up Water level at upstream of the orifice. [m AD]
DR

orifice_s1dn Water level at downstream of the orifice. [m AD]

orifice_gate_opening_ Gate opening height of the orifice. [m]
height
orifice_head Head difference across the orifice. [m]
∗
orifice_flow_area Flow area at the orifice. [m2 ]
∗
orifice_state Flow state at the orifice. Possible values:
⋄ 0: No flow
⋄ 1: free weir flow
⋄ 2: submerged weir flow
⋄ 3: free gate flow
⋄ 4: submerged gate flow
orifice_velocity∗ Velocity through the orifice. [m/s]
orifice_s1_on_crest∗ Water level on crest of the orifice. [m AD]
∗
orifice_force_difference Force difference per unit width at the orifice. [N/m]

Remarks:
⋄ Variables with notation ∗ show a fill value (-999) if the flow link is dry. When the orifice covers
more than one flow link, the written variables are either summed across all wet links (e.g. dis-
charge and area), or a weighted average, with the weights being the widths of the wet flow links
(e.g. water level on crest and force difference per unit width). Specially, velocity is the summed
discharge divided by the summed area on wet links.
⋄ orifice_s1up shows a fill value (-999) when the upstream cell is dry. If there is more than
one upstream cell, then the value is a weighted average, with the weights being the widths of the
flow links whose corresponding upstream cells are wet. This also applies to orifice_s1dn
considering downstream cells.
⋄ orifice_head has a valid value only when both upstream and downstream cells are wet.
Otherwise it shows a fill value (-999). This means that, when the upstream cell is dry while
downstream cell is wet, orifice_head has a fill value (-999). In the situation when there

Deltares 498 of 562

 Output files

is more than one upstream/downstream cell, the value is a weighted average, with the weights
being the widths of the flow links whose corresponding upstream and downstream cells are both
wet.
⋄ orifice_state shows a fill value (-999) if the flow link is dry. When the orifice covers more
than one wet flow link, then the state may differ per flow link. If not all of the flow links have the
same state value, the state is written to file as a fill value (-999).

F.3.1.8.5 Bridge
Output for bridge structures is available as time series in the history file. The output can be switched
on or off using the MDU setting [output] wriHis_structure_bridge (cf. Table A.1). The

T
available output quantities are listed in Table F.10.

Table F.10: Output quantities of bridges in history file.

Quantity name Description Unit

AF bridge_id
bridge_discharge∗
bridge_s1up
Id of the bridge.
Discharge through the bridge.
Water level at upstream of the bridge.
[m3 /s]
[m AD]
bridge_s1dn Water level at downstream of the bridge. [m AD]
bridge_head Head difference across the bridge. [m]
∗
bridge_flow_area Flow area at the bridge. [m2 ]
bridge_velocity∗ Velocity through the bridge. [m/s]
bridge_blup Bed level at upstream of the bridge. [m AD]
bridge_bldn Bed level at downstream of the bridge. [m AD]
DR

bridge_bl_actual Actual bed level of bridge (crest) that is used [m AD]

in the computation.

Remarks:
⋄ Variables with notation ∗ show a fill value (-999) if the flow link is dry. When the bridge covers
more than one flow link, the written variables are summed across all wet links (e.g. discharge
and area). Specially, velocity is the summed discharge divided by the summed area on wet
links.
⋄ bridge_s1up shows a fill value (-999) when the upstream cell is dry. If there is more than
one upstream cell, then the value is a weighted average, with the weights being the widths of
the flow links whose corresponding upstream cells are wet. This also applies to bridge_s1dn
considering downstream cells.
⋄ bridge_head has a valid value only when both upstream and downstream cells are wet.
Otherwise it shows a fill value (-999). This means that, when the upstream cell is dry while
downstream cell is wet, bridge_head has a fill value (-999). In the situation when there is
more than one upstream/downstream cell, the value is a weighted average, with the weights
being the widths of the flow links whose corresponding upstream and downstream cells are
both wet.
⋄ When the bridge covers more than one flow link, variables of bed level (with bl) are weighted
averages, with the weights being the widths of the flow links (both dry and wet).
⋄ The actual bed level of the bridge is a crest-like bed level, i.e., at the velocity point.

F.3.1.8.6 Culvert
Output for culvert structures is available as time series in the history file. The output can be switched
on or off using the MDU setting [output] wriHis_structure_culvert (cf. Table A.1). The
available output quantities are listed in Table F.11.

Deltares 499 of 562

 Output files

Table F.11: Output quantities of culverts in history file.

Quantity name Description Unit

culvert_id Id of the culvert.
∗
culvert_discharge Discharge through the culvert. [m3 /s]
culvert_crest_level Crest level. [m AD]
culvert_gate_lower_edge_ Gate lower edge level. [m AD]
level
culvert_s1up Water level at upstream of the culvert. [m AD]

T
culvert_s1dn Water level at downstream of the culvert. [m AD]
culvert_gate_opening_ Gate opening height of the culvert. [m]
height
culvert_head Head difference across the culvert. [m]
∗
culvert_flow_area Flow area at the culvert. [m2 ]
AF culvert_state ∗
Flow state at the culvert. Possible values:
⋄ 0: No flow
⋄ 1: free culvert flow
⋄ 2: submerged culvert flow
culvert_velocity∗ Velocity through the culvert. [m/s]

Remarks:
⋄ Variables with notation ∗ show a fill value (-999) if the flow link is dry. When the culvert covers
more than one flow link, the written variables are summed across all wet links (e.g. discharge
DR

and area). Specially, velocity is the summed discharge divided by the summed area on wet
links.
⋄ culvert_s1up shows a fill value (-999) when the upstream cell is dry. If there is more than
one upstream cell, then the value is a weighted average, with the weights being the widths of the
flow links whose corresponding upstream cells are wet. This also applies to culvert_s1dn
considering downstream cells.
⋄ culvert_head has a valid value only when both upstream and downstream cells are wet.
Otherwise it shows a fill value (-999). This means that, when the upstream cell is dry while
downstream cell is wet, culvert_head has a fill value (-999). In the situation when there
is more than one upstream/downstream cell, the value is a weighted average, with the weights
being the widths of the flow links whose corresponding upstream and downstream cells are both
wet.
⋄ culvert_state shows a fill value (-999) if the flow link is dry. When the culvert covers more
than one wet flow link, then the state may differ per flow link. If not all of the flow links have the
same state value, the state is written to file as a fill value (-999).

F.3.1.8.7 Long culvert

Output for long culvert structures is available as time series in the history file. The output can be
switched on or off using the MDU setting [output] wriHis_structure_longculvert (cf.
Table A.1). The available output quantities are listed in Table F.12.

Table F.12: Output quantities of long culverts in history file.

Quantity name Description Unit

longculvert_id Id of the long culvert.
∗
longculvert_discharge Discharge through the long culvert. [m3 /s]
longculvert_s1up Water level at upstream of the long culvert. [m AD]
(continued on next page)

Deltares 500 of 562

 Output files

Quantity name Description Unit

(continued from previous page)
longculvert_s1dn Water level at downstream of the long culvert. [m AD]
longculvert_head Head difference across the long culvert. [m]
∗
longculvert_flow_area Flow area at the long culvert. [m2 ]
longculvert_velocity∗ Velocity through the long culvert. [m/s]
longculvert_valve_ Valve relative opening in long culvert. [1]
relative_opening∗

T
Remarks:
⋄ Variables with notation ∗ show a fill value (-999) if the flow link is dry. When the long culvert
covers more than one flow link, the written variables are summed across all wet links (e.g.
discharge and area). Specially, velocity is the summed discharge divided by the summed area
AF on wet links.
⋄ longculvert_s1up shows a fill value (-999) when the upstream cell is dry. If there is
more than one upstream cell, then the value is a weighted average, with the weights being
the widths of the flow links whose corresponding upstream cells are wet. This also applies to
longculvert_s1dn considering downstream cells.
⋄ longculvert_head has a valid value only when both upstream and downstream cells are
wet. Otherwise it shows a fill value (-999). This means that, when the upstream cell is dry while
downstream cell is wet, longculvert_head has a fill value (-999). In the situation when
there is more than one upstream/downstream cell, the value is a weighted average, with the
weights being the widths of the flow links whose corresponding upstream and downstream cells
are both wet.
⋄ In the case of a long culvert that consists of more than one wet flow link (refer to Figure 12.11):
DR

⋄ the discharge is used from the first flow link, i.e., the inlet side.
⋄ the upstream and downstream water levels are taken from the 2D end points of the long
culvert structure. No output on any intermediate pressure points is written in the his file.
Those can be found in the map file.

F.3.1.8.8 Dam break

Output for dam break structures is available as time series in the history file. The output can be
switched on or off using the MDU setting [output] wriHis_structure_damBreak (cf. Ta-
ble A.1). The available output quantities are listed in Table F.13.

Table F.13: Output quantities of dam breaks in history file.

Quantity name Description Unit

dambreak_id Id of the dam break.
dambreak_s1up Water level at upstream of the dam break. [m AD]
dambreak_s1dn Water level at downstream of the dam break. [m AD]
∗
dambreak_discharge Discharge through the dam break. [m3 /s]
dambreak_cumulative_ Cumulative discharge through the dam break. [m3 /s]
discharge∗
dambreak_breach_width_ Breach width time derivative of the dam break. [m/s]
time_derivative
dambreak_water_level_jump Breach water level jump across the dam [m]
break. See remark below.
dambreak_normal_velocity Normal velocity through the dam break. [m/s]
dambreak_structure_head Head difference across the dam break. [m]
(continued on next page)

Deltares 501 of 562

 Output files

Quantity name Description Unit

(continued from previous page)
dambreak_flow_area∗ Flow area at the dam break. [m2 ]
dambreak_crest_level Actual crest level that is used in the computa- [m AD]
tion. When there is no breach yet, the crest
level is the bed level ("bob") at the breach
starting location.
dambreak_crest_width Actual crest width that is used in the compu- [m]
tation. When there is no breach yet, equal to
0.

T
Remarks:
⋄ Contrary to all other hydraulic structures, the dam break output only includes flow through the
breach hole. In a 2D model, when multiple flow links are crossed by the dambreak polyline,
AF there may additionally be flow across the fixed weir crest levels of flow links even though the
breach growth has not reached them yet. When the total discharge across the entire polyline is
desired, it is recommended to include an additional observation cross section (Section F.2.4) in
the model.
⋄ In a similar way as in the previous point, water levels and other quantities are only averaged or
summed over the flow links in the breach hole.
⋄ Variables with notation ∗ show a fill value (-999) if the flow link is dry. When the dambreak covers
more than one flow link, the written variables are summed across all wet links (e.g. discharge
and area).
⋄ dambreak_s1up shows a fill value (-999) when the upstream cell is dry. If there is more than
one upstream cell, then the value is a weighted average, with the weights being the widths of the
flow links whose corresponding upstream cells are wet. This also applies to dambreak_s1dn
DR

considering downstream cells.

⋄ dambreak_structure_head has a valid value only when both upstream and downstream
cells are wet. Otherwise it shows a fill value (-999). This means that, when the upstream cell
is dry while downstream cell is wet, dambreak_structure_head has a fill value (-999). In
the situation when there is more than one upstream/downstream cell, the value is a weighted
average, with the weights being the widths of the flow links whose corresponding upstream and
downstream cells are both wet.
⋄ The quantities dambreak_structure_head and dambreak_water_level_jump are
different. The head is the basic difference between up- and downstream water levels. The water
level jump is equal to max(0, ζup − zs ) − max(0, ζdn − zs ) and represents the average water
level jump at the breach crest, often used in breach growth formulas.

F.3.1.8.9 Universal weir

Output for universal weir structures is available as time series in the history file. The output can be
switched on or off using the MDU setting [output] wriHis_structure_uniWeir (cf. Ta-
ble A.1). The available output quantities are listed in Table F.14.

Table F.14: Output quantities of universal weirs in history file.

Quantity name Description Unit

uniweir_id Id of the universal weir.
∗
uniweir_discharge Discharge through the universal weir. [m3 /s]
uniweir_s1up Water level at upstream of the universal weir. [m AD]
uniweir_s1dn Water level at downstream of the universal [m AD]
weir.
uniweir_head Head difference across the universal weir. [m]
∗
uniweir_flow_area Flow area at the universal weir. [m2 ]
(continued on next page)

Deltares 502 of 562

 Output files

Quantity name Description Unit

(continued from previous page)
uniweir_velocity∗ Velocity through the universal weir. [m/s]
uniweir_crest_level Crest level of the universal weir. [m AD]

Remarks:
⋄ Variables with notation ∗ show a fill value (-999) if the flow link is dry. When the universal
weir covers more than one flow link, the written variables are summed across all wet links (e.g.

T
discharge and area). Specially, velocity is the summed discharge divided by the summed area
on wet links.
⋄ uniweir_s1up shows a fill value (-999) when the upstream cell is dry. If there is more than
one upstream cell, then the value is a weighted average, with the weights being the widths of the
flow links whose corresponding upstream cells are wet. This also applies to uniweir_s1dn
considering downstream cells.
AF ⋄ uniweir_head has a valid value only when both upstream and downstream cells are wet.
Otherwise it shows a fill value (-999). This means that, when the upstream cell is dry while
downstream cell is wet, uniweir_head has a fill value (-999). In the situation when there
is more than one upstream/downstream cell, the value is a weighted average, with the weights
being the widths of the flow links whose corresponding upstream and downstream cells are both
wet.

F.3.1.8.10 Compound structure

Output for compound structures is available as time series in the history file. The output can be
switched on or off using the MDU setting [output] wriHis_structure_compound (cf. Ta-
ble A.1). The available output quantities are listed in Table F.15.
DR

Table F.15: Output quantities of compound structures in history file.

Quantity name Description Unit

cmpstru_id Id of the compound structure.
∗
cmpstru_discharge Total discharge through the compound struc- [m3 /s]
ture.
cmpstru_s1up Water level at upstream of the compound [m AD]
structure.
cmpstru_s1dn Water level at downstream of the compound [m AD]
structure.
cmpstru_head Head difference across the compound struc- [m]
ture.
cmpstru_flow_area∗ Total flow area at the compound structure. [m2 ]
cmpstru_velocity∗ Average velocity through the compound struc- [m/s]
ture.

Remarks:
⋄ Variables with notation ∗ show a fill value (-999) if the flow link is dry. When the compound
structure covers more than one flow link, the written variables are summed across all wet links
(e.g. discharge and area). Specially, velocity is the summed discharge divided by the summed
area on wet links.
⋄ cmpstru_s1up shows a fill value (-999) when the upstream cell is dry. If there is more than
one upstream cell, then the value is a weighted average, with the weights being the widths of the
flow links whose corresponding upstream cells are wet. This also applies to cmpstru_s1dn
considering downstream cells.
⋄ cmpstru_head has a valid value only when both upstream and downstream cells are wet.
Otherwise it shows a fill value (-999). This means that, when the upstream cell is dry while

Deltares 503 of 562

 Output files

downstream cell is wet, cmpstru_head has a fill value (-999). In the situation when there
is more than one upstream/downstream cell, the value is a weighted average, with the weights
being the widths of the flow links whose corresponding upstream and downstream cells are both
wet.

F.3.1.8.11 Summary
Table F.16 summarizes the above output quantities for different hydraulic structures, where the exis-
tence of output is denoted by ×.

Table F.16: Summary of output in history files of quantities for different structures.

T
Quantity name Pump General Weir Orifice Bridge Culvert Dam Universal Compound Long
structure break Weir structure cul-
vert
Id of structure × × × × × × × × × ×
AF Total discharge through structure
Discharge through gate opening
× ×
×
× × × × × × × ×

Discharge over gate upper edge level ×

Water level at upstream of the structure × × × × × × × × × ×
Water level at downstream of the structure × × × × × × × × × ×
Crest level of structure × × × × × ×
Gate opening height of structure × × ×
Gate lower edge level of structure × × ×
Gate upper edge level of structure ×
DR

Crest width of structure × × × ×

Force difference per unit width × × ×
Water level on crest of structure × × ×
Head difference across structure × × × × × × × × × ×
Velocity through structure × × × × × × × ×
Velocity through gate opening ×
Velocity over gate upper edge level ×
Flow area at structure × × × × × × × × ×
Flow area in gate opening ×
Flow area above upper edge level ×
Flow state at structure × × × ×
Actual stage of pump ×
Capacity of pump ×
Discharge w.r.t. pump orientation ×
Head difference in pumping direction ×
Reduction factor of pump ×
Water level at delivery side of pump ×
Water level at suction side of pump ×
Coordinates of representative of pump ×
Gate opening width ×
Cumulative discharge through dambreak ×
Breach width time derivative of dambreak ×
Breach water level jump of dambreak ×
(continued on next page)

Deltares 504 of 562

 Output files

Quantity name Pump General Weir Orifice Bridge Culvert Dam Universal Compound Long
structure break Weir structure cul-
vert
(continued from previous page)
Normal velocity through dambreak ×
Bed level at upstream of bridge ×
Bed level at downstream of bridge ×
Actual bed level of bridge ×
Valve relative opening ×

T
Geometry variables × × × × × × × ×

F.3.1.9 Geometry variables

Geometry variables2 , that are also written to the his-files, give the geometry information for those
AF locations for which time series are reported in the his-file. NOTE: the location information of geometry
variables does not give the original input location of the geometries, but rather the locations that are
snapped to the computational mesh.

For a set of geometries, there are four geometry variables. Take a set of general structures as an
example. The geometry variables names contain "_geom" for readability, but this is not required, and
they should be identified via CF-compliant attributes. For the set of general structures these are:
⋄ "general_structure_geom",
⋄ "general_structure_geom_node_count",
⋄ "general_structure_geom_node_coordx",
⋄ "general_structure_geom_node_coordy".
DR

The description of the above geometry variables are as follows:

⋄ "general_structure_geom" is a geometry container variable. Such a variable can typically be iden-
tified when it is referenced in the :geometry attribute of another data variable, and the container
variable itself has the :geometry_type attribute. This variable contains all the attributes that
describe this set of geometries, including the following attributes:
"geometry_type": tells the type of the geometry. It can be "point", "line" or "polygon".
⋄ ⋄

"node_count": tells the name of a variable that indicates the count of nodes per geometry. The
name is "general_structure_geom_node_count" in our example, and it will contain the number
of geometry points for each of the general structures in the model input.
"node_coordinates": contains the names of variables that contain the node coordinates of
⋄

the geometry. In our example, it has two names "general_structure_geom_node_coordx" and

"general_structure_geom_node_coordy".
⋄ "_node_count": indicates the total number of nodes on this set of geometries. For instance, if
variable "general_structure_geom_node_count" contains values "2, 3", it means that there are two
general structures, and the first and the second general structures have 2 and 3 nodes, respec-
tively.
⋄ "_node_coordx": gives x-coordinates of all the nodes. Take the above example, then this array will
contain 5 points in total; the first 2 values of this variable are the x-coordinates of the 2 nodes of
the first general structure, and next 3 values of this variable are the x-coordinates of the 3 nodes of
the second general structure.
⋄ "_node_coordy": gives y-coordinates of all the nodes.

The following geometries in his files have geometry variables:

⋄ Observation points.
⋄ Observation cross sections.
2
For more details about geometry variables please see: https://github.com/cf-convention/cf-conventions/blob/
main/ch07.adoc#geometries

Deltares 505 of 562

 Output files

⋄ Hydraulic structures, including:

Weirs.
⋄ ⋄ ⋄ ⋄ ⋄ ⋄ ⋄ Orifices.
General structures.
Universal weirs.
Gates.
Pumps.
Bridges.
⋄ Source and sinks.
⋄ Laterals.

T
F.3.2 Spatial fields as netCDF map-file
The map file <mdu_name_map.nc> contains data on the entire model grid in 1D, 2D and 3D. Three
formats are currently supported, selected by the MapFormat keyword in the mdu-file:
AF [output]
MapFormat = 4 # Map file format, 1: netCDF, 2: Tecplot,
# 3: netCFD and Tecplot, 4: netCDF-UGRID

D-Flow FM is using the more standardized UGRID3 format. This is the default option. D-Flow FM GUI
and Delft3D-QUICKPLOT also support this format. In the examples below the older netCDF format is
still shown, but most of the concepts discussed hereafter apply equally well to UGRID output (4), only
the variable names will be slightly different.
DR

For parallel runs, each process writes a separate file for each partition as <mdu_name_000X_map.nc>.

The map file contains the dimensions and variable definitions in its header, followed by the actual data.

Dimensions
The following dimensions are defined in a map file header:

netcdf weirfree_map {
dimensions:
nNetNode = 310 ;
nNetLink = 486 ;
nNetLinkPts = 2 ;
nBndLink = 252 ;
nNetElem = 180 ;
nNetElemMaxNode = 4 ;
nNetLinkContourPts = 4 ;
nFlowElem = 180 ; // Nr.
of grid cells
nFlowElemMaxNode = 4 ;
nFlowElemContourPts = 4 ;
nFlowLink = 246 ; // Nr.
of flow links (open cell edges)
nFlowLinkPts = 2 ;
time = UNLIMITED ; // (64 currently)

For plotting solution data, the grid cells (flow nodes) are important, and the flow links (open cell edges).
All Net* dimensions relate the flow grid tot the original unstructured network. More explanation of
these topological naming conventions can be found in section 22.1.

3
https://github.com/ugrid-conventions/ugrid-conventions

Deltares 506 of 562

 Output files

Location variables
The location and shape of grid cells is stored in several x,y variables:

double FlowElem_xcc(nFlowElem) ;
FlowElem_xcc:units = "m" ;
FlowElem_xcc:standard_name = "projection_x_coordinate" ;
FlowElem_xcc:long_name = "Flow element circumcenter x" ;
FlowElem_xcc:bounds = "FlowElemContour_x" ;
double FlowElem_ycc(nFlowElem) ;
FlowElem_ycc:units = "m" ;
FlowElem_ycc:standard_name = "projection_y_coordinate" ;

T
FlowElem_ycc:long_name = "Flow element circumcenter y" ;
FlowElem_ycc:bounds = "FlowElemContour_y" ;
// [..]
double FlowElemContour_x(nFlowElem, nFlowElemContourPts) ;
FlowElemContour_x:units = "m" ;
FlowElemContour_x:standard_name = "projection_x_coordinate" ;
FlowElemContour_x:long_name = "List of x-points forming flow element" ;

;
AFFlowElemContour_x:_FillValue = -999.

// [..]
double FlowElem_bl(nFlowElem) ;
FlowElem_bl:units = "m" ;
FlowElem_bl:positive = "up" ;
FlowElem_bl:standard_name = "sea_floor_depth" ;
FlowElem_bl:long_name = "Bottom level at flow element\'s circumcenter." ;

In 3D output the map file also contains the vertical dimensions laydim for the layer centers and wdim
for the layer interfaces. Corresponding to these dimensions, vertical coordinates LayCoord_cc and
LayCoord_w, respectively are added:
DR

double LayCoord_cc(laydim) ;
LayCoord_cc:standard_name = "" ;
LayCoord_cc:long_name = "z layer coordinate at flow element center" ;
LayCoord_cc:positive = "up" ;
LayCoord_cc:units = "m" ;
double LayCoord_w(wdim) ;
LayCoord_w:standard_name = "" ;
LayCoord_w:long_name = "z layer coordinate at vertical interface" ;
LayCoord_w:positive = "up" ;
LayCoord_w:units = "m" ;

These variable contain time- and space-independent layer positions (either in absolute z, or relative
sigma coordinates).

In the case the FullGridOutput option is active (FullGridOutput = 1), these vertical coordi-
nates LayCoord_cc and LayCoord_w are excluded from the map-file and replaced by variables
FlowElem_zcc and FlowElem_zw. These variables contain the vertical positions of layer centers
and interfaces, respectively, written for each flow cell and each timestep separately. Currently, this is
only the case for the flow cell (centre) positions and not for the horizontal flow link positions:

double FlowElem_zcc(time, nFlowElem, laydim) ;

FlowElem_zcc:coordinates = "FlowElem_xcc FlowElem_ycc FlowElem_zcc" ;
FlowElem_zcc:standard_name = "" ;
FlowElem_zcc:long_name = "flow element center z" ;
FlowElem_zcc:units = "m" ;
double FlowElem_zw(time, nFlowElem, wdim) ;
FlowElem_zw:coordinates = "FlowElem_xcc FlowElem_ycc FlowElem_zw" ;
FlowElem_zw:standard_name = "" ;
FlowElem_zw:long_name = "flow element z at vertical interface" ;
FlowElem_zw:units = "m" ;

Deltares 507 of 562

 Output files

Variables on grid cells/pressure points

Variables on grid cells (represented by the pressure point/cell circumcenter) are typically defined as
follows:

double s1(time, nFlowElem) ;

s1:coordinates = "FlowElem_xcc FlowElem_ycc" ;
s1:standard_name = "sea_surface_level" ;
s1:long_name = "waterlevel" ;
s1:units = "m" ;
s1:grid_mapping = "projected_coordinate_system" ;

T
All quantities that are available in the map file are listed in Table F.17 and Table F.18. These quantities
are output when the model contains the related object. For example, quantities about waves are output
in map file only when the model contains wave computation.
AF
DR

Deltares 508 of 562

 DR
Deltares

Table F.17: Output variables in map file of UGRID format. Column ’Location’ shows the grid location: CN means cell corners. L means net links. S means
pressure points, U means velocity points. S3D and U3D are the corresponding locations in 3D networks. Two more locations in 3D networks are:
W, vertical velocity point on all layer interfaces, and WU, vertical viscosity point on all layer interfaces.

Quantity name MDU option Unit Location

A
Water level at end of time step. wriMap_waterlevel_s1 [m AD] S
Water depth at pressure points. wriMap_waterdepth [m] S
Water level at start of time step. wriMap_waterlevel_s0 [m AD] S
Numlimdt: number of times each cell was limiting the time step. wriMap_numlimdt [–] S

FT
Temperature. wriMap_temperature [◦ C] S or S3D
Tracers and other constituents. wriMap_constituents [-] S or S3D
# The followings are hydrological quantities (??):
Rainfall intensity. wriMap_rain [m/s] S
Interception layer water depth. wriMap_interception [m] S
Potential evaporation. wriMap_evaporation [m/s] S
Actual evaporation. wriMap_evaporation [m/s] S
Prescribed evaporation rate. wriMap_evaporation [m/s] S
# The above are hydrological quantities.
# The following variables are only for 3D models:
Vertical coordinate of layer centres at pressure points. FullGridOutput [m] S3D
Vertical coordinate of layer interfaces at pressure points. FullGridOutput [m] W
Bounds of vertical coordinate of layers at pressure points. FullGridOutput [m] S3D
Vertical coordinate of layer centres at velocity points. FullGridOutput [m] U3D
Bounds of vertical coordinate of layers at velocity points. FullGridOutput [m] U3D
Turbulent kinetic energy, if [numerics] Turbulencemodel >= 3. wriMap_turbulence [m2 /s2 ] WU
Turbulent vertical eddy viscosity, if wriMap_turbulence [m2 /s] WU
[numerics] Turbulencemodel >= 3.

Output files
Turbulent energy dissipation, if [numerics] Turbulencemodel = 3. wriMap_turbulence [m2 /s3 ] WU
509 of 562

Turbulent time scale, if [numerics] Turbulencemodel = 4. wriMap_turbulence [1/s] WU

Flow element center velocity vector, z-component. wriMap_velocity_vector [m/s] S3D
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name MDU option Unit Location
Flow element center GLM depth-averaged velocity if wriMap_velocity_vector [m/s] S
[output] EulerVelocities = 1 and
[waves] Wavemodelnr > 0. Otherwise, flow element center

A
depth-averaged velocity. This includes x- and y-components.
Flow element center depth-averaged GLM velocity magnitude if wriMap_velocity_magnitude [m/s] S
[output] EulerVelocities = 1 and
[waves] Wavemodelnr > 0. Otherwise, flow element center
depth-averaged velocity magnitude.

FT
Upward velocity on vertical interface, n-component. wriMap_upward_velocity_component [m/s] W
3
Flow element center mass density. wriMap_density_rho [kg/m ] S3D
# The above variables are only for 3D models.
Sum of all water influx. wriMap_Qin [m3 /s] S
Volume of water in grid cell. wriMap_volume1 [m3 ] S or S3D
Time step per cell based on CFL. wriMap_DTcell [s] S or S3D
Water depth at velocity points. wriMap_waterdepth_hu [m] U
Wet flow area between two neighbouring grid cells. wriMap_flowarea_au [m2 ] U or U3D
Velocity at velocity points, n-component. wriMap_velocity_component_u1 [m/s] U or U3D
Velocity at velocity points at previous time step, n-component. wriMap_velocity_component_u0 [m/s] U or U3D
Flow element center eulerian velocity vector if wriMap_velocity_vector [m/s] S or S3D
[output] EulerVelocities = 1 and
[waves] Wavemodelnr > 0 and [waves] flowWithoutWaves is
false. Otherwise, flow element center velocity vector. This includes x- and
y-components.
Flow element center eulerian velocity magnitude if wriMap_velocity_magnitude [m/s] S or S3D
[output] EulerVelocities = 1 and
[waves] Wavemodelnr > 0 and [waves] flowWithoutWaves is
false. Otherwise, flow element center velocity magnitude.

Output files
(continued on next page)
510 of 562
 DR
Deltares

(continued from previous page)

Quantity name MDU option Unit Location
Flow element center eulerian velocity vector based on discharge if wriMap_velocity_vectorq [m/s] S or S3D
[output] EulerVelocities = 1 and
[waves] Wavemodelnr > 0 and [waves] flowWithoutWaves is

A
false. Otherwise, flow element center velocity vector based on discharge. This
includes x- and y-components.
Discharge through flow link at current time. wriMap_flow_flux_q1 [m3 /s] U or U3D
Main channel discharge through flow link at current time. wriMap_flow_flux_q1_main [m3 /s] U or U3D

FT
2
Horizontal eddy viscosity. wriMap_horizontal_viscosity_viu [m /s] U or U3D
Horizontal eddy diffusivity. wriMap_horizontal_diffusivity_diu [m2 /s] U or U3D
2
Total bed shear stress vector, including x- and y-components. wriMap_taucurrent [N/m ] S
Total bed shear stress magnitude. wriMap_taucurrent [N/m2 ] S
Bed shear stress magnitude for morphology if both MDU keywords wriMap_taucurrent [N/m2 ] S
[sediment] SedFile and MorFile are not empty, and
Sedimentmodelnr is 4.
# The following variables are about roughness:
Chézy roughness:
Effective Chézy roughness in flow element center. wriMap_chezy [m0.5 /s] S
Effective Chézy roughness on flow links. wriMap_chezy_on_flow_links [m0.5 /s] U
Input roughness on flow links. wriMap_input_roughness Depends on roughness type. U
Input roughness type. wriMap_input_roughness [-], see UnifFrictType in Table A.1. U
Energy loss for fixed weirs in case of Tabellenboek or Villemonte if wriMap_fixed_weir_energy_loss [m] U or U3D
[numerics] FixedWeirScheme = 8 or 9
Salinity in flow element if [physics] Salinity > 0. wriMap_salinity [ppt] S or S3D
# The following variables are about streamline curvature and spiral flow intensity (section 3.6):
(For non-3D models only) Flow streamline curvature if wriMap_spiral_flow [1/m] S
[physics] SecondaryFlow is positive.

Output files
Spiral flow intensity if [physics] SecondaryFlow > 0. [m/s] S
511 of 562

wriMap_spiral_flow
# The above variables are about streamline curvature and spiral flow intensity.
Names of all water quality bottom variables in flow element. [depends] S
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name MDU option Unit Location
Names of all water quality bottom variables in flow element with suffix _3D. wriMap_wqBot3d [depends] S3D
Extra water quality output. [depends] S or S3D
All water quality statistic variables. [depends] S or S3D

A
Water quality mass balance areas. [-] S
2
Atmospheric pressure near surface. wriMap_wind [N/m ] S
Wind velocity on flow element center, including x- and y-components. wriMap_wind [m/s] S

FT
Wind velocity on flow links, including x- and y-components. wriMap_wind [m/s] U
Wind stress on flow element center, including x- and y-components. wriMap_windstress [N/m2 ] S
# The following variables are about heat flux quantities, air temperature, relative humidity, cloudiness and more detailed fluxes (chapter 5):
Air temperature near surface. wriMap_heat_fluxes [◦ C] S
Relative humidity near surface. wriMap_heat_fluxes [-] S
Cloudiness. wriMap_heat_fluxes [1] S
Solar influx. wriMap_heat_fluxes [W/m2 ] S
2
Evaporative heat flux. wriMap_heat_fluxes [W/m ] S
Sensible heat flux. wriMap_heat_fluxes [W/m2 ] S
2
Long wave back radiation. wriMap_heat_fluxes [W/m ] S
Free convection evaporative heat flux. wriMap_heat_fluxes [W/m2 ] S
Free convection sensible heat flux. wriMap_heat_fluxes [W/m2 ] S
2
Total heat flux. wriMap_heat_fluxes [W/m ] S
# The above variables are about heat flux quantities, air temperature, relative humidity, cloudiness and more detailed fluxes.
Time-varying bottom level in flow cell center, if wriMap_sediment [m] S
[sediment] Sedimentmodelnr > 0 and [sediment] SedFile
and MorFile are not empty, and Sedimentmodelnr is 4, or if the EXT file
contains bedrock_surface_elevation.
Cumulative subsidence/uplift, if the EXT file contains [m] S, U or CN

Output files
bedrock_surface_elevation.
512 of 562

Current related roughness height. wriMap_z0 [m] U

Current-wave related roughness height. wriMap_z0 [m] U
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name MDU option Unit Location
# The following variables are for models with sediment (Deltares (2025d)),
# when [sediment] Sedimentmodelnr > 0 and [sediment] SedFile and MorFile are not empty, Sedimentmodelnr is 4.
Time interval over which cumulative transports are calculated, if MorFile wriMap_sediment [s] -

A
keyword [output] AverageAtEachOutputTime is false.
Average morphological factor over elapsed morphological time. wriMap_sediment [-] -
Current morphological time. wriMap_sediment [s] -
Sediment fraction name. wriMap_sediment [-] -

FT
Suspended sediment fraction name. wriMap_sediment [-] -
(For 3D models only) Bottom layer for sed calculations. wriMap_sediment [-] S
Sediment settling velocity. wriMap_sediment [m/s] W for 3D,
otherwise S
(For non-3D models only) Equilibrium sediment concentration. wriMap_sediment [kg/m3 ] S
Near-bed reference concentration height, if MorFile keyword wriMap_sediment [m] S
[Output] ReferenceHeight is true.
Near-bed reference concentration, if MorFile keyword wriMap_sediment [kg/m3 ] S
[Output] ReferenceHeight is true.
Source term suspended sediment fractions, if MorFile keyword wriMap_sediment [kg/m3 /s] S
[Output] SourceSinkTerms is true.
Sink term suspended sediment fractions, if MorFile keyword wriMap_sediment [1/s] S
[Output] SourceSinkTerms is true.
(For 3D models only) Near-bed transport correction in face-normal direction, if wriMap_sediment [kg/s/m] if MorFile keyword U
MorFile keyword [Output] NearBedTranspCorrAtFlux is true. [Output] TranspType is 0, or
[m3 /s/m] if MorFile keyword
[Output] TranspType is 1 or 2.
Sediment concentration. wriMap_sediment [kg/m3 ] S or S3D
Suspended load transport, including n- and t-components. wriMap_sediment [kg/s/m] if MorFile keyword U
[Output] TranspType is 0, or

Output files
[m3 /s/m] if MorFile keyword
513 of 562

[Output] TranspType is 1 or 2.
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name MDU option Unit Location
Bed load transport, including n- and t-components. wriMap_sediment [kg/s/m] if MorFile keyword U
[Output] TranspType is 0, or
[m3 /s/m] if MorFile keyword

A
[Output] TranspType is 1 or 2.
Bed slope, including n- and t-components, if MorFile keyword wriMap_sediment [-] U
[Output] Bedslope is true.
Characteristic velocity in cell centre, including n- and t-components, if MorFile wriMap_sediment [m/s] S
keyword [Output] VelocAtZeta is true.

FT
Characteristic velocity magnitude, if MorFile keyword wriMap_sediment [m/s] S
[Output] VelocMagAtZeta is true.
Height above bed for characteristic velocity, if MorFile keyword wriMap_sediment [m] S
[Output] VelocZAtZeta is true.
Bed shear velocity, if MorFile keyword [Output] ShearVeloc is true. wriMap_sediment [m/s] S
Bed load transport due to currents, including x- and y-components, if MorFile wriMap_sediment [kg/s/m] if MorFile keyword S
keyword [Output] BedTranspDueToCurrentsAtZeta and [Output] TranspType is 0, or
[Output] RawTransportsAtZeta are true. [m3 /s/m] if MorFile keyword
[Output] TranspType is 1 or 2.
Bed load transport due to currents (reconstructed), including x- and wriMap_sediment [kg/s/m] if MorFile keyword S
y-components, if MorFile keyword [Output] TranspType is 0, or
[Output] BedTranspDueToCurrentsAtZeta is true. [m3 /s/m] if MorFile keyword
[Output] TranspType is 1 or 2.
Bed load transport due to waves, including x- and y-components, if MorFile wriMap_sediment [kg/s/m] if MorFile keyword S
keyword [Output] BedTranspDueToWavesAtZeta and [Output] TranspType is 0, or
[Output] RawTransportsAtZeta are true. [m3 /s/m] if MorFile keyword
[Output] TranspType is 1 or 2.
Bed load transport due to waves (reconstructed), including x- and wriMap_sediment [kg/s/m] if MorFile keyword S
y-components, if MorFile keyword [Output] TranspType is 0, or
[Output] BedTranspDueToWavesAtZeta is true. [m3 /s/m] if MorFile keyword
[Output] TranspType is 1 or 2.

Output files
514 of 562

Suspended load transport due to currents, including x- and y-components, if wriMap_sediment [kg/s/m] if MorFile keyword S
MorFile keyword [Output] SuspTranspDueToCurrentsAtZeta and [Output] TranspType is 0, or
[Output] RawTransportsAtZeta are true. [m3 /s/m] if MorFile keyword
[Output] TranspType is 1 or 2.
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name MDU option Unit Location
Suspended load transport due to currents (reconstructed), including x- and wriMap_sediment [kg/s/m] if MorFile keyword S
y-components, if MorFile keyword [Output] TranspType is 0, or
[Output] SuspTranspDueToCurrentsAtZeta is true. [m3 /s/m] if MorFile keyword

A
[Output] TranspType is 1 or 2.
Suspended load transport due to waves, including x- and y-components, if wriMap_sediment [kg/s/m] if MorFile keyword S
MorFile keyword [Output] SuspTranspDueToWavesAtZeta and [Output] TranspType is 0, or
[Output] RawTransportsAtZeta are true. [m3 /s/m] if MorFile keyword
[Output] TranspType is 1 or 2.

FT
Suspended load transport due to waves (reconstructed), including x- and wriMap_sediment [kg/s/m] if MorFile keyword S
y-components, if MorFile keyword [Output] TranspType is 0, or
[Output] SuspTranspDueToWavesAtZeta is true. [m3 /s/m] if MorFile keyword
[Output] TranspType is 1 or 2.
Total sediment transport (reconstructed), including x- and y-components. wriMap_sediment [kg/s/m] if MorFile keyword S
[Output] TranspType is 0, or
[m3 /s/m] if MorFile keyword
[Output] TranspType is 1 or 2.
Time-averaged bed load, including x- and y-components, if MorFile keyword wriMap_sediment [kg/s/m] if MorFile keyword S
[Output] AverageAtEachOutputTime is true. [Output] TranspType is 0, or
[m3 /s/m] if MorFile keyword
[Output] TranspType is 1 or 2.
Time-averaged suspended load transport, including x- and y-components. wriMap_sediment [kg/s/m] if MorFile keyword S
[Output] TranspType is 0, or
[m3 /s/m] if MorFile keyword
[Output] TranspType is 1 or 2.
Available sediment mass in the bed, if MorFile keyword wriMap_sediment [kg/m2 ] S
[Underlayer] IUnderLyr = 1.
Sediment thickness in the bed, if MorFile keyword wriMap_sediment [m] S
[Underlayer] IUnderLyr = 1.
Available sediment mass in a layer of the bed, if MorFile keyword wriMap_sediment [kg/m2 ] S

Output files
[Underlayer] IUnderLyr = 2.
515 of 562

Thickness of a layer of the bed, if MorFile keyword wriMap_sediment [m] S

[Underlayer] IUnderLyr = 2.
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name MDU option Unit Location
Porosity of a layer of the bed, if MorFile keyword wriMap_sediment [-] S
[Underlayer] IUnderLyr = 2 and
[Underlayer] IPorosity > 0.

A
Volume fraction in a layer of the bed, if MorFile keyword wriMap_sediment [-] S
[Underlayer] IUnderLyr = 2.
Bed shear stress for morphology, if MorFile keyword [Output] Taub is wriMap_sediment [N/m2 ] S
true.

FT
Excess bed shear ratio, if MorFile keyword [Output] taurat is true. wriMap_sediment [-] S
Arithmetic mean sediment diameter, if MorFile keyword [Output] Dm is wriMap_sediment [m] S
true.
Geometric mean sediment diameter, if MorFile keyword [Output] Dg is wriMap_sediment [m] S
true.
Geometric standard deviation of particle size mix, if MorFile keyword wriMap_sediment [m] S
[Output] Dgsd is true.
All sediment diameter percentile, if MorFile keyword wriMap_sediment [m] S
[Output] Percentiles is true.
Availability fraction in top layer, if MorFile keyword [Output] Frac is true. wriMap_sediment [-] S
Mud fraction in top layer, if MorFile keyword [Output] MudFrac is true. wriMap_sediment [-] S
Sand fraction in top layer, if MorFile keyword [Output] SandFrac is true. wriMap_sediment [-] S
Reduction factor due to limited sediment thickness, if MorFile keyword wriMap_sediment [-] S
[Output] FixFac is true.
Hiding and exposure factor, if MorFile keyword [Output] HidExp is true. wriMap_sediment [-] S
2
Sediment mass in fluff layer, if MorFile keyword wriMap_sediment [kg/m ] S
[FluffLayer] Type > 0.
(For 1D only) Time-varying cross-section points level, if MorFile keyword wriMap_sediment [m] S
[Morphology] BedUpd is true.
(For 1D only) Time-varying cross-section points width, if MorFile keyword wriMap_sediment [m] S

Output files
[Morphology] BedUpd is true.
516 of 562

(For 1D only) Name of cross-section, if MorFile keyword wriMap_sediment [-] S

[Morphology] BedUpd is true.
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name MDU option Unit Location
(For 1D only) Main channel averaged bed level, if MorFile keyword wriMap_sediment [m] S
[Output] MainChannelAveragedBedLevel is true.
(For 1D only) Main channel cell area, if MorFile keyword wriMap_sediment [m2 ] S

A
[Output] MainChannelCellArea is true.
(For 1D only) Main channel cell width, if MorFile keyword wriMap_sediment [m] U
[Output] MainChannelWidthAtFlux is true.
# The above variables are for models with sediment (Deltares (2025d)),

FT
# when [sediment] Sedimentmodelnr > 0 and [sediment] SedFile and MorFile are not empty, Sedimentmodelnr is 4.
# The following variables are for models with sediment,
# when [sediment] Sedimentmodelnr > 0, and either [sediment] SedFile or MorFile is empty or Sedimentmodelnr is not 4.
All sediment concentrations. wriMap_sediment [kg/m3 ] S
All erodable layer thickness per size fraction in flow element centers,if MDU wriMap_sediment [m] S
keyword [sediment] Jaceneqtr = 1.
Flow element center bedlevel (bl),if MDU keyword wriMap_sediment [m] S
[sediment] Jaceneqtr = 1.
All erodable layer thickness per size fraction in flow element corners,if MDU wriMap_sediment [m] CN
keyword [sediment] Jaceneqtr is not 1.
Flow element corner bedlevel (zk),if MDU keyword wriMap_sediment [m] CN
[sediment] Jaceneqtr is not 1.
# The above variables are for models with sediment,
# when [sediment] Sedimentmodelnr > 0, and either [sediment] SedFile or MorFile is empty or Sedimentmodelnr is not 4.
# The following variables are for flow without waves, when [waves] flowWithoutWaves is true.
RMS wave height, if EXT file contains hrms or wriMap_waves [m] S
wavesignificantheight, and MDU keyword
[waves] jamapsigwav = 0.
Significant wave height, if EXT file contains hrms or wriMap_waves [m] S
wavesignificantheight, and MDU keyword

Output files
517 of 562

[waves] jamapsigwav is non-zero.

Peak wave period, if EXT file contains tp or tps or rtp or waveperiod. wriMap_waves [s] S
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name MDU option Unit Location
Mean direction of wave propagation relative to ksi-dir. ccw, if EXT file contains wriMap_waves [deg] S
dir or wavedirection.
Mean direction of wave propagation relative to ksi-dir. ccw, if EXT file contains wriMap_waves [deg] S

A
dir or wavedirection.
Surface layer wave forcing term, x-component, if EXT file contains fx. wriMap_waves [N/m2 ] S
2
Surface layer wave forcing term, y-component, if EXT file contains fy. wriMap_waves [N/m ] S
Bottom layer wave forcing term, x-component, if EXT file contains wsbu. wriMap_waves [N/m2 ] S

FT
Bottom layer wave forcing term, y-component, if EXT file contains wsbv. wriMap_waves [N/m2 ] S
3
Wave-induced volume flux in x-direction, if EXT file contains mx. wriMap_waves [m /s/m] S
Wave-induced volume flux in y-direction, if EXT file contains my. wriMap_waves [m3 /s/m] S
2
Wave energy dissipation rate at the free surface, if EXT file contains wriMap_waves [w/m ] S
dissurf.
Wave energy dissipation rate due to white capping, if EXT file contains wriMap_waves [w/m2 ] S
diswcap.
Wave orbital velocity, if EXT file contains ubot. wriMap_waves [m/s] S
# The above variables are for flow without waves, when [waves] flowWithoutWaves is true.
# The following variables are for flow with waves, when [waves] flowWithoutWaves is false.
Wave energy per square meter, if MDU keyword wriMap_waves [J/m2 ] S
[waves] Wavemodelnr = 4.
Roller energy per square meter, if MDU keyword wriMap_waves [J/m2 ] S
[waves] Wavemodelnr = 4.
Roller energy dissipation per square meter, if MDU keyword wriMap_waves [W/m2 ] S
[waves] Wavemodelnr = 4.
Wave breaking energy dissipation per square meter, if MDU keyword wriMap_waves [W/m2 ] S
[waves] Wavemodelnr = 4.
Wave bottom energy dissipation per square meter, if MDU keyword wriMap_waves [W/m2 ] S

Output files
[waves] Wavemodelnr = 4.
518 of 562

Radiation stress, including x- and y-components, if MDU keyword wriMap_waves [N/m2 ] S

[waves] Wavemodelnr = 4.
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name MDU option Unit Location
2
Radiation stress, xy-component, if MDU keyword wriMap_waves [N/m ] S
[waves] Wavemodelnr = 4.
Sea surface wave phase celerity, if MDU keyword wriMap_waves [m/s] S

A
[waves] Wavemodelnr = 4.
Sea surface wave group celerity, if MDU keyword wriMap_waves [m/s] S
[waves] Wavemodelnr = 4.
Sea surface wave mean frequency, if MDU keyword wriMap_waves [rad/s] S

FT
[waves] Wavemodelnr = 4.
Sea surface wave wavenumber, if MDU keyword wriMap_waves [rad/m] S
[waves] Wavemodelnr = 4.
Sea surface wave ratio group phase speed, if MDU keyword wriMap_waves [-] S
[waves] Wavemodelnr = 4.
Sea surface wave refraction celerity, if MDU keyword wriMap_waves [rad/s] S
[waves] Wavemodelnr = 4.
Sea surface wave wavelength, if MDU keyword wriMap_waves [m] S
[waves] Wavemodelnr = 4 and windmodel, read from the specified
file in MDU keyword [waves] SurfbeatInput, is 1.
Wind source term on wave energy, if MDU keyword wriMap_waves [J/m2 /s] S
[waves] Wavemodelnr = 4, and windmodel and windsource that
are read from the specified file in MDU keyword
[waves] SurfbeatInput, are 1.
Wind source term on wave period, if MDU keyword wriMap_waves [s/s] S
[waves] Wavemodelnr = 4, and windmodel and windsource,
read from the specified file in MDU keyword [waves] SurfbeatInput,
are 1.
(For 3D models only) Surface layer wave forcing term, including x- and wriMap_waves [N/m2 ] S
y-components, if MDU keyword [waves] Wavemodelnr is 3 or 4.
(For 3D models only) Water body wave forcing term, including x- and wriMap_waves [N/m2 ] S

Output files
y-components, if MDU keyword [waves] Wavemodelnr is 3 or 4.
519 of 562

RMS wave height, if MDU keyword [waves] Wavemodelnr > 0 and wriMap_waves [m] S
[waves] jamapsigwav = 0.
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name MDU option Unit Location
Significant wave height, if MDU keyword [waves] Wavemodelnr > 0 wriMap_waves [m] S
and [waves] jamapsigwav is non-zero.
Wave orbital velocity, if MDU keyword [waves] Wavemodelnr > 0. wriMap_waves [m/s] S

A
Stokes drift including x- and y-components, if MDU keyword wriMap_waves [m/s] S or S3D
[waves] Wavemodelnr > 0.
Stokes drift including n- and t-components, if MDU keyword wriMap_waves [m/s] U or U3D
[waves] Wavemodelnr > 0.

FT
Wave from direction, if MDU keyword [waves] Wavemodelnr > 0. wriMap_waves [deg from N] S
Wave period, if MDU keyword [waves] Wavemodelnr > 0. wriMap_waves [s] S
Wave force including x- and y-components, if MDU keyword wriMap_waves [N/m2 ] S or S3D
[waves] Wavemodelnr is 3 or 4.
Wave force at velocity point including n- and t-components, if MDU keyword wriMap_waves [N/m2 ] U or U3D
[waves] Wavemodelnr is 3 or 4.
# The above variables are for flow with waves, when [waves] flowWithoutWaves is false.
Time-varying dune height, if BedformFile keyword [bedform] BdfOut [m] S
and [bedform] Bdf are true.
Time-varying dune length, if BedformFile keyword [bedform] BdfOut [m] S
and [bedform] Bdf are true.
Ripple roughness height, if BedformFile keyword [bedform] BdfOut is [m] S
true and, either MDU keywords [waves] Wavemodelnr > 0 and
[waves] Rouwav = VR04, or Van Rijn 2004 transport formula is used.
Megaripple roughness height, if BedformFile keyword [bedform] BdfOut [m] S
is true and, either MDU keywords [waves] Wavemodelnr > 0 and
[waves] Rouwav = VR04, or Van Rijn 2004 transport formula is used.
Dune roughness height, if BedformFile keyword [bedform] BdfOut is [m] S
true and, either MDU keywords [waves] Wavemodelnr > 0 and
[waves] Rouwav = VR04, or Van Rijn 2004 transport formula is used.

Output files
Bedform roughness height, if BedformFile keyword [bedform] BdfOut is [m] S
520 of 562

true and, either MDU keywords [waves] Wavemodelnr > 0 and

[waves] Rouwav = VR04, or Van Rijn 2004 transport formula is used.
# The following variables are for trachytope roughness:
(continued on next page)
 DR
Deltares

(continued from previous page)

Quantity name MDU option Unit Location
0.5
Chezy roughness from trachytopes, if MDU keyword wriMap_trachytopes [m /s] L
[physics] UnifFrictType = 0.
Manning roughness from trachytopes, if MDU keyword wriMap_trachytopes [s/m0.333 ] L

A
[physics] UnifFrictType = 1.
White-Colebrook roughness from trachytopes, if MDU keyword wriMap_trachytopes [m] L
[physics] UnifFrictType is 2 or 3.
Roughness from trachytopes, if MDU keyword wriMap_trachytopes [-] L

FT
[physics] UnifFrictType is not equal to 0, 1, 2, or 3.
Stem density of vegetation. [1/m2 ] S
Stem diameter of vegetation. [m] S
Stem height of vegetation. [m] S
Calibration factor for roughness. wriMap_calibration [m0.5 /s] L
# The above variables are for trachytope roughness.
# The following variables are about nudging, when the EXT file contains nudge_salinity_temperature.
Nudging relaxing time. wriMap_nudging [s] S
Nudging temperature. wriMap_nudging [◦ C] S3D
Nudging salinity. wriMap_nudging [1e-3] S3D
Difference of nudging temperature with temperature. wriMap_nudging [◦ C] S3D
Difference of nudging salinity with salinity. wriMap_nudging [1e-3] S3D
# The above variables are about nudging, when the EXT file contains nudge_salinity_temperature.

Output files
521 of 562
 Output files

Variables on flow links/velocity points

Variables on grid cell edges (represented by the velocity point) are typically defined as follows:

double q1(time, nFlowLink) ;

q1:coordinates = "FlowLink_xu FlowLink_yu" ;
q1:long_name = "Flow flux" ;
q1:units = "m3 s-1" ;

Other quantities that can be written are:

T
⋄ Normal velocities at the old and new time level;
⋄ Horizontal viscosity and diffusivity;
⋄ Edge-centered wind speed components;
⋄ Effective roughness values from trachytopes/vegetation (section 13.2)
AF
Variables for flow analysis
By selecting wriMap_flow_analysis = 1 under [Output] in the MDU file, a number of flow
analysis variables will be written to the map file. These variables can be used to find possible bottle-
necks in the model.

Table F.18: Flow analysis variables in the map file. Column ’Location’ shows the grid
location: S means pressure points, U means velocity points.

Quantity name Unit Location

Number of times negative depth was calculated. [-] S
DR

Cumulative number of times negative depth was calculated. [-] S

Number of times no nonlinear convergence was caused [-] S
Cumulative number of times no nonlinear convergence was [-] S
caused
Number of times a node was limiting for the computational [-] S
time step
Cumulative number of times a node was limiting for the com- [-] S
putational time step
Courant number [-] S

Remarks:
⋄ During the simulation, the non-linear iteration can calculate negative depths. In general an oc-
casional negative depth does not affect the simulation. However frequently calculated negative
depths can be the cause of strange results or instabilities.
⋄ The report of ’no convergence in the non linear iteration’ (counted in Number of times
no nonlinear convergence is caused), is a strong indicator that something might
be wrong with the model. This count is incremented for the flow node that showed the largest
water level difference in the last nonlinear iteration.
⋄ The performance of a model is affected by the maximal timestep that can be used during the sim-
ulation. In Number of times a node was limiting for the computational
time step the locations that are bottlenecks for the maximal timestep can be found. Using
this information, the locations that are restricting for the maximal timestep can be investigated.
Subsequently an attempt can be made to find a solution to reduce these bottlenecks.
⋄ The Courant number is the limiting factor for the maximal timestep. This variable can be used
to investigate whether only a few locations are limiting the timestep or whether it uniformly
distributed across the complete model domain.
⋄ The Courant number is an instantaneous value, valid for the moment the output is written
to the map file.

Deltares 522 of 562

 Output files

⋄ The other output variables come in two forms. The first of each two variables contains the
number of occurrences during the past map output interval, whereas the second (denoted with
"Cumulative"/_cum) contains the total number of occurrences since the start of the simulation
until the current map output time.

F.3.3 Class map files as netCDF clm-file

The class map option gives output in a netCDF file, where the size of the output file is significantly less
then the size of a map-file. This is achieved by storing the field of interest (currently only water levels
and water depths) not as a double (8 bytes), but as a byte that represents the class it is in. As the
class will not change every time, compressing is used to get even smaller files than the factor 8 based

T
on the ratio double/byte.

This format is very suitable for making animations of dryfall and flooding.

The class map file is defined in the mdu-file by:

AF [output]
...
ClassMapFile = weirfree_clm.nc # Filename for class map output
WaterlevelClasses = -3.0 2.0 5.0 # Water level classes (m)
WaterdepthClasses = 0.5 1.0 5.0 10.0 # Water depth classes (m)
ClassMapInterval = 5.0 # Class map output interval (s)

The class map file is always in UGRID format. When running in parallel, a class map file is generated
for each process. Use mapmerge to collect them in a single file.
DR

F.3.4 Restart files as netCDF rst-file

Restart files <mdu_name_yyyymmdd_HHMMSS_rst.nc> are almost identical to map files, except
that they contain all data for just a single time. The grid and flow geometry information is not present,
except for the flow cell/link coordinates. Moreover, restart files resulted from a parallel run contains
parallelization information. For this reason, restart files are less suitable for plotting, but efficient for
restarting a computation.

F.3.5 Volume tables per- gridpoint output as netCDF file

Dimensions
The per- gridpoint output net file contains all 1D flow geometry dimensions, plus the volume table levels
and increment:

netcdf PerGridpoint_TestModel_01 {
dimensions:
Two = 2 ;
network1d_nEdges = 4 ;
network1d_nNodes = 5 ;
network1d_nGeometryNodes = 141 ;
strLengthIds = 40 ;
strLengthLongNames = 80 ;
mesh1d_nNodes = 28 ;
mesh1d_nEdges = 27 ;
nmesh1d_FlowElemContourPts = 7 ;
levels = 45 ;
increment = 1 ;

Furthermore full network information is included:

Deltares 523 of 562

 Output files

int network1d ;
network1d:cf_role = "mesh_topology" ;
network1d:long_name = "Topology data of 1D network" ;
network1d:edge_dimension = "network1d_nEdges" ;
network1d:edge_geometry = "network1d_geometry" ;
network1d:edge_node_connectivity = "network1d_edge_nodes" ;
network1d:node_coordinates = "network1d_node_x network1d_node_y" ;
network1d:node_dimension = "network1d_nNodes" ;
network1d:topology_dimension = 1 ;
network1d:node_id = "network1d_node_id" ;
network1d:node_long_name = "network1d_node_long_name" ;
network1d:branch_id = "network1d_branch_id" ;

T
network1d:branch_long_name = "network1d_branch_long_name" ;
network1d:edge_length = "network1d_edge_length" ;
int network1d_edge_nodes(network1d_nEdges, Two) ;
network1d_edge_nodes:cf_role = "edge_node_connectivity" ;
network1d_edge_nodes:long_name = "Start and end nodes of network edges" ;
char network1d_branch_id(network1d_nEdges, strLengthIds) ;
network1d_branch_id:long_name = "ID of branch geometries" ;
char network1d_branch_long_name(network1d_nEdges, strLengthLongNames) ;
AF network1d_branch_long_name:long_name = "Long name of branch geometries" ;
double network1d_edge_length(network1d_nEdges) ;
network1d_edge_length:long_name = "Real length of branch geometries" ;
network1d_edge_length:units = "m" ;
char network1d_node_id(network1d_nNodes, strLengthIds) ;
network1d_node_id:long_name = "ID of network nodes" ;
char network1d_node_long_name(network1d_nNodes, strLengthLongNames) ;
network1d_node_long_name:long_name = "Long name of network nodes" ;
double network1d_node_x(network1d_nNodes) ;
network1d_node_x:units = "m" ;
network1d_node_x:standard_name = "projection_x_coordinate" ;
network1d_node_x:long_name = "x-coordinate of network nodes" ;
double network1d_node_y(network1d_nNodes) ;
network1d_node_y:units = "m" ;
network1d_node_y:standard_name = "projection_y_coordinate" ;
network1d_node_y:long_name = "y-coordinate of network nodes" ;
DR

int network1d_geometry ;
network1d_geometry:geometry_type = "line" ;
network1d_geometry:long_name = "1D Geometry" ;
network1d_geometry:node_count = "network1d_geom_node_count" ;
network1d_geometry:node_coordinates = "network1d_geom_x network1d_geom_y" ;
int network1d_geom_node_count(network1d_nEdges) ;
network1d_geom_node_count:long_name = "Number of geometry nodes per branch" ;
double network1d_geom_x(network1d_nGeometryNodes) ;
network1d_geom_x:units = "m" ;
network1d_geom_x:standard_name = "projection_x_coordinate" ;
network1d_geom_x:long_name = "x-coordinate of branch geometry nodes" ;
double network1d_geom_y(network1d_nGeometryNodes) ;
network1d_geom_y:units = "m" ;
network1d_geom_y:standard_name = "projection_y_coordinate" ;
network1d_geom_y:long_name = "y-coordinate of branch geometry nodes" ;
int network1d_branch_order(network1d_nEdges) ;
network1d_branch_order:long_name = "Order of branches for interpolation" ;
network1d_branch_order:mesh = "network1d" ;
network1d_branch_order:location = "edge" ;
int network1d_branch_type(network1d_nEdges) ;
network1d_branch_type:long_name = "Type of branches" ;
network1d_branch_type:mesh = "network1d" ;
network1d_branch_type:location = "edge" ;

As is the 1D mesh topology information:

int mesh1d ;
mesh1d:cf_role = "mesh_topology" ;
mesh1d:long_name = "Topology data of 1D mesh" ;
mesh1d:topology_dimension = 1 ;
mesh1d:coordinate_space = "network1d" ;
mesh1d:edge_node_connectivity = "mesh1d_edge_nodes" ;
mesh1d:node_dimension = "mesh1d_nNodes" ;
mesh1d:edge_dimension = "mesh1d_nEdges" ;
mesh1d:node_coordinates = "mesh1d_node_branch mesh1d_node_offset
mesh1d_node_x mesh1d_node_y" ;

Deltares 524 of 562

 Output files

mesh1d:edge_coordinates = "mesh1d_edge_branch mesh1d_edge_offset

mesh1d_edge_x mesh1d_edge_y" ;
mesh1d:node_id = "mesh1d_node_id" ;
mesh1d:node_long_name = "mesh1d_node_long_name" ;
int mesh1d_node_branch(mesh1d_nNodes) ;
mesh1d_node_branch:long_name = "Index of branch on which mesh nodes are
mesh1d_node_branch:start_index = 0 ;
double mesh1d_node_offset(mesh1d_nNodes) ;
mesh1d_node_offset:long_name = "Offset along branch of mesh nodes" ;
mesh1d_node_offset:units = "m" ;
double mesh1d_node_x(mesh1d_nNodes) ;
mesh1d_node_x:units = "m" ;
mesh1d_node_x:standard_name = "projection_x_coordinate" ;
mesh1d_node_x:long_name = "x-coordinate of mesh nodes" ;

T
mesh1d_node_x:bounds = "mesh1d_FlowElemContour_x" ;
double mesh1d_node_y(mesh1d_nNodes) ;
mesh1d_node_y:units = "m" ;
mesh1d_node_y:standard_name = "projection_y_coordinate" ;
mesh1d_node_y:long_name = "y-coordinate of mesh nodes" ;
mesh1d_node_y:bounds = "mesh1d_FlowElemContour_y" ;
int mesh1d_edge_branch(mesh1d_nEdges) ;
AF mesh1d_edge_branch:long_name = "Index of branch on which mesh edges are
mesh1d_edge_branch:start_index = 0 ;
double mesh1d_edge_offset(mesh1d_nEdges) ;
mesh1d_edge_offset:long_name = "Offset along branch of mesh edges" ;
mesh1d_edge_offset:units = "m" ;
double mesh1d_edge_x(mesh1d_nEdges) ;
mesh1d_edge_x:units = "m" ;
mesh1d_edge_x:standard_name = "projection_x_coordinate" ;
mesh1d_edge_x:long_name = "Characteristic x-coordinate of the mesh edge ;
double mesh1d_edge_y(mesh1d_nEdges) ;
mesh1d_edge_y:units = "m" ;
mesh1d_edge_y:standard_name = "projection_y_coordinate" ;
mesh1d_edge_y:long_name = "Characteristic y-coordinate of the mesh edge ;
char mesh1d_node_id(mesh1d_nNodes, strLengthIds) ;
mesh1d_node_id:long_name = "ID of mesh nodes" ;
char mesh1d_node_long_name(mesh1d_nNodes, strLengthLongNames) ;
DR

mesh1d_node_long_name:long_name = "Long name of mesh nodes" ;

int mesh1d_edge_nodes(mesh1d_nEdges, Two) ;
mesh1d_edge_nodes:cf_role = "edge_node_connectivity" ;
mesh1d_edge_nodes:long_name = "Start and end nodes of mesh edges" ;
mesh1d_edge_nodes:start_index = 1 ;
double mesh1d_FlowElemContour_x(mesh1d_nNodes, nmesh1d_FlowElemContourPts) ;
mesh1d_FlowElemContour_x:units = "m" ;
mesh1d_FlowElemContour_x:standard_name = "projection_x_coordinate" ;
mesh1d_FlowElemContour_x:long_name = "list of x-coordinates forming flow
mesh1d_FlowElemContour_x:_FillValue = -999. ;
double mesh1d_FlowElemContour_y(mesh1d_nNodes, nmesh1d_FlowElemContourPts) ;
mesh1d_FlowElemContour_y:units = "m" ;
mesh1d_FlowElemContour_y:standard_name = "projection_y_coordinate" ;
mesh1d_FlowElemContour_y:long_name = "list of y-coordinates forming flow
mesh1d_FlowElemContour_y:_FillValue = -999. ;

Finally it contains the actual volume table data written. For the per- gridpoint output the volume and
surface arrays are two dimensional, containing a value per volume table level for every 1D node.

double volume(mesh1d_nNodes, levels) ;

volume:long_name = "Volume" ;
volume:units = "m3" ;
double surface(mesh1d_nNodes, levels) ;
surface:long_name = "Surface" ;
surface:units = "m2" ;
int numlevels(mesh1d_nNodes) ;
numlevels:long_name = "Number of levels" ;
numlevels:units = "" ;
double bedlevel(mesh1d_nNodes) ;
bedlevel:long_name = "Bedlevel" ;
bedlevel:units = "m" ;
double topheight(mesh1d_nNodes) ;
topheight:long_name = "TopHeight" ;
topheight:units = "m" ;
double increment(increment) ;

Deltares 525 of 562

 Output files

increment:long_name = "Increment" ;
increment:units = "m" ;

F.3.6 NetCDF versions and file formats

The supported netCDF file formats are netCDF 3 and 4, configurable in the MDU via the [output]
NcFormat keyword. Format 3 is the default for all netCDF output files, except for the classmap file,
which always uses netCDF 4, because it uses compression.

The precision of the data written to the map-file and his-file can be configured in the MDU using the

T
keywords [output] NcMapDataPrecision and [output] NcHisDataPrecision. Note
that the station coordinates are always written in double precision for accuracy.

Compression of the his-file can be enabled by setting [output] NcCompression=1. Note that
this feature only works when [output] NcFormat=4.
AF
F.4 Shapefiles
Shapefiles4 are widely used for visualization in geographic information system (GIS) software. A
shapefile stores geometric locations and corresponding attributes information for the spatial features.
D-Flow FM can generate shapefiles by setting keyword in the MDU file. Table F.19 shows what features
can be written to a shapefile by D-Flow FM, and the corresponding MDU settings. (By default these
keywords are zero, which disables writing the shapefile.) Moreover, this function is also valid in parallel
simulation.

Table F.19: Features and MDU settings for generating shapefiles

DR

Features for shapefiles MDU setting

Cross sections [output] Wrishp_crs = 1

Dambreaks [output] Wrishp_dambreak = 1
Dry area [output] Wrishp_dryarea = 1
Embankments [output] Wrishp_ebm = 1
Fixed weirs [output] Wrishp_fxw = 1
Gates [output] Wrishp_gate= 1
General structures [output] Wrishp_genstruc = 1
Observation stations [output] Wrishp_obs = 1
Pump [output] Wrishp_pump = 1
Source-sinks [output] Wrishp_src = 1
Thin dams [output] Wrishp_thd = 1
Weirs [output] Wrishp_weir= 1

F.5 Post processing on his-file

There are three options for post processing on the history file. Two options are for finding the maximum
value and one for the running mean maximum value for each history station or cross section. They are
options of the program dfmoutput.

4
https://www.esri.com/library/whitepapers/pdfs/shapefile.pdf

Deltares 526 of 562

 Output files

F.5.1 Max25 function

The max25 function computes statistics for all stations in the his-file. Basic statistics includes the
first, minimum, maximum and last value. It computes a running mean over the given filter
length in time (by default two filter lengths: 13 and 25). For this running mean the minimum, maximum
and last value are computed. The maximum value of the running mean over 25 points (in time) is
abbreviated to max25.

Basic usage for max25 is:

T
dfmoutput max25 --infile [hisfile.nc]

AF There are three optional arguments:

--outfile [name of the outputfile], default max25.out

--varname [variable to find maximum for], default waterlevel
--filterlength [list of numbers of points in time], default two values 13, 25

F.5.2 Maximum based on a generic filter

The second option is to find the maximum value after applying a 4th order monotone filter on the time
serie for each station. This filter has three parameters: the filter length and two coefficients. These
parameters can be given by the user, see below.

Basic usage for maximum based on a generic filter is:

DR

dfmoutput genfilter --infile [hisfile.nc]

There are five optional arguments:

--outfile [name of the outputfile], default max.out

--varname [variable to find maximum for], default waterlevel
--intval [filter period], default 6
--coefimpl [filter coefficient implicit part], default 0.3
--coefexpl [filter coefficient explicit part], default 0.3

F.5.3 Maximum based on a running mean filter

The third option is a maximum based on a running mean filter, the same as can be used in the fou-file.
See C.14 for a definition of this filter.

Basic usage for maximum based on a running mean is:

dfmoutput max_running_mean --infile [hisfile.nc]

There are three optional arguments:

--outfile [name of the outputfile], default max_running_mean.out

--varname [variable to find maximum for], default waterlevel
--filterlength [filter lengths], default two values 13, 25

Deltares 527 of 562

 G Model generation

G.1 Introduction
Parts of the model building process can also be automated, to support model generation. This comes
in addition to the full modelling process as described in chapter 7.

G.2 Grid generation

Automated grid generation is limited to a few basic types, described hereafter. More specific grid

T
generation should be done by the modeller in RGFGRID. Automated grid generation is currently done
from the commandline using the dflowfm-cli.exe program (dflowfm on Linux).

G.2.1 Uniform Cartesian grid

AF A uniform Cartesian (i.e., rectangular) grid can be generated by specifying the bounding box and
desired grid resolution:

> dflowfm-cli.exe --gridgen:x0=xLL :y0=yLL :dx=∆x:dy=∆y:ncols=M :nrows=N

This produces a file <out_net.nc>. When the coordinate system for the grid should be spherical
(WGS84), add the option :spherical=1.
DR

G.2.2 Locally refined Cartesian grid

An existing grid can be locally refined based on an additional input file that defines the refinement loca-
tions. Here, we will now consider a uniform Cartesian (i.e., rectangular) that needs to be refined based
on a raster file (e.g. an ArcInfo file). The grid refinement is currently based on ’Courant’ refinement,
but this can be applied to different refinement metrics as well. The command for refinement is:

> dflowfm-cli.exe --refine:hmin=∆xmin :dtmax=∆tmax :connect=1:outsidecell=1

unif_net.nc refineC.asc

The input file <unif_net.nc> is a file that has been produced by the --gridgen command (for
this Cartesian case, see section G.2.1), for example with a grid resolution ∆xmax . The input file
<refineC.asc> should contain values 1 for locations that need the finest size ∆xmin , 4 for one step
coarser, 16 for two steps coarser. In general: 22n , with n the number of coarsening
√ steps. The value
of ∆tmax is a fictitious value here, and should be set to ∆tmax = ∆xmin / 9.81. When entering only
a few decimal digits for ∆tmax , make sure to round it up.

This again produces a file <out_net.nc>.

Deltares 528 of 562

 H Spatial editor

H.1 Introduction
The spatial editor is a generic feature of the User Interface for editing spatial data (e.g. bed level,
roughness, viscosity, initial conditions, sediment availability). The spatial editor supports both point
clouds and coverages (e.g. data on a grid or network). Therefore, you can use the spatial editor both
to edit spatial data in general and to prepare model input. This Chapter describes the general features
of the spatial editor (section H.2), (spatial) quantity selection (section H.3), geometry operations (sec-
tion H.4), spatial operations (section H.5) and the operation stack (section H.6). The examples given
below are typically focusing on use of the spatial editor in the D-Flow FM User Manual.

T
AF
Figure H.1: Overview of spatial editor functionality in Map ribbon

H.2 General

H.2.1 Overview of spatial editor

The spatial editor functionality can be accessed from the “Spatial Operations” ribbon (Figure H.1).
DR

Typically, you first select which data set or quantity (either a point cloud or a coverage) to work on
(e.g. bed level, roughness, viscosity, initial conditions, sediment availability), then a geometry (e.g.
point, line, polygon) and finally which spatial operation to perform (e.g. crop, delete, set value, contour,
interpolate, smoothing). Typical workflows are as follows:

Working on a point cloud dataset:

1 Import the dataset as point cloud (section H.2.2)
2 Activate/select the dataset (quantity) in the spatial editor (section H.3)
3 Select a geometry to perform an operation on (section H.4)
4 Select the spatial operation for this geometry (section H.5)
5 Repeat steps 3 and 4 until you are satisfied with the data
6 Export the dataset (section H.6.7)

Working on a coverage (e.g. model input):

1 Activate/select the spatial quantity to work on in the spatial editor (section H.3)
2 Optional: import a dataset as point cloud (section H.5.1)
3 Select a geometry to perform an operation on (section H.4)
4 Select the spatial operation for this geometry (section H.5)
5 Repeat steps 3 and 4 until you are satisfied with the data
6 Interpolate the point cloud to the grid or network (section H.5.10)
7 Optional: export the dataset (section H.6.7)

Upon performing a spatial operation, the ‘Operations’ panel will open (see Figure H.53) with the opera-
tions stack. This stack keeps track of the workflow of spatial operations that you performed. This helps
you to make transparent how you arrived at your ‘final’ dataset without having to save all the intermedi-
ate datasets (steps) separately. Moreover, the stack is reproducible and easily editable without having
to start all over again. When working on a coverage (e.g. the second workflow), point clouds can be
used to construct the coverage. In this case the coverage (for example ‘Bed level’) is the ‘trunk’ of the
workflow and the point clouds (appearing as sets in the stack) are ‘branches’ or subsets of this trunk
(see Figure H.53). By selecting the set or coverage in the ‘Operations’ panel you determine on which

Deltares 529 of 562

 Spatial editor

dataset you are working. The interpolate operation (section H.5.10) allows you to bring data from the
point cloud (branch) to the coverage (trunk). For more information on the stack you are referred to
section section H.6.

H.2.2 Import/export dataset

To import a (point cloud) dataset use the context menu on “project” in the “Project Tree”, select “import”
from the context menu and select the option "Points from XYZ-file" (Figure H.2). There is yet another
method to import the point cloud. Click on "Import" icon under the Home ribbon to obtain a drop-down
menu with the list of importers. Select the option "Points from XYZ-file" under Spatial data section
(Figure H.3) to launch the import wizard.

T
After the import, the point cloud will be added to the project tree. To activate the point cloud in the
spatial editor, either double click the dataset in the project tree (Figure H.4) or select it from the drop
down box in the spatial editor ribbon (Figure H.5).
AF Note: Exporter still to be implemented
DR

Figure H.2: Importing a point cloud into the project using the context menu on “project” in
the project tree

Deltares 530 of 562

 Spatial editor

T
AF Figure H.3: Importing a point cloud into the project using the "Import" drop-down menu in
the Spatial Operations ribbon

Figure H.4: Activate the imported point cloud in the spatial editor by double clicking it in
DR

the project tree

Figure H.5: Activate the imported point cloud in the spatial editor by selecting it from the
dropdown box in the Map ribbon

H.2.3 Activate (spatial) model quantity

Similar to activating an imported dataset in the spatial editor, you can also activate a (spatial) model
quantity (e.g. bed level, initial conditions, roughness, viscosity) in the spatial editor by double clicking
the quantity in the project tree or selecting it from the dropdown box in the “Spatial Operations” ribbon.

Deltares 531 of 562

 Spatial editor

H.2.4 Colorscale
In the spatial editor the colorscale for a spatial quantity can be made visible in the map window by
clicking on the ”Legend" button in the “Spatial Operations” ribbon (Figure H.6). Then, in the Map
window a colorscale is activated (Figure H.7). You can (de-)activate the color scale by clicking on the
“Legend” button again. By default the colorscale is ranging from the minimum to the maximum value
of the active dataset.

T
Figure H.6: Legend button in Map ribbon
AF
DR

Figure H.7: Activate the colorscale by using the Legend in the map ribbon and the col-
orscale will become visible in the map window.

You can adjust the colormap and classes of the colorscale using the context menu on the spatial
quantity in the “Map tree” and selecting “Legend Properties” (Figure H.8 left panel). A layer properties
editor will open in which you can set the colormap to your own preferences (Figure H.8 right panel).

Deltares 532 of 562

 Spatial editor

T
AF
Figure H.8: Edit the colorscale properties using the context menu on the active layer in
the Map Tree
DR

H.2.5 Render mode

By default point clouds are rendered as (colored) points and coverages as shades (e.g. ‘FillSmooth’).
The render mode can be edited using the properties of the active layer Figure H.9. The User Interface
offers the following render modes:
⋄ Points
⋄ Lines (only for coverages)
⋄ Shades or ‘FillSmooth’ (only for coverages)
⋄ Colored numbers
⋄ Mono colored numbers

An example of a coverage rendered as colored numbers is given in Figure H.10.

Deltares 533 of 562

 Spatial editor

T
AF
DR

Figure H.9: Select the rendermode for the active layer in the property grid.

Figure H.10: Example of a coverage rendered as colored numbers.

H.2.6 Context menu

In addition to the selection of spatial operation from the ‘Spatial Operations’ ribbon (see section H.5),
you can also select spatial operations using the context menu (e.g. context menu). After drawing a
geometry and clicking the context menu all spatial operation available for the geometry will pop-up
(see Figure H.11). The spatial operation will become active upon selecting it from the context menu.

Deltares 534 of 562

 Spatial editor

T
AF Figure H.11: Selecting a smoothing operation for a polygon geometry from the context
menu (using context menu)

H.3 Quantity selection

A spatial quantity can be activated/selected either by double clicking it in the project tree (Figure H.12)
or by selecting it from the dropdown box in the “Spatial Operations” ribbon (Figure H.13). Upon select-
ing the spatial quantity it will be shown as a point cloud (for a dataset) or coverage (for model input) on
the central map. Typically, you start from a point cloud (either obtained from import or by generating
DR

samples yourself) which will eventually be interpolated to a grid or network (e.g. coverage). The spatial
editor will keep track of both the changes made to the point cloud(s) and coverage of the selected
spatial quantity. The information will be saved in the User Interface project and available the next time
you open the project. Note: The operations are not yet saved in a human-readable/editable file

Figure H.12: Activating a spatial quantity by double clicking it in the project tree (in this
example ‘Initial Water Level’)

Deltares 535 of 562

 Spatial editor

Figure H.13: Activating a spatial quantity by selecting it from the dropdown box in the
‘Spatial Operations’ ribbon

T
H.4 Geometry operations
The spatial editor supports three types of geometry operations: (1) polygons, (2) lines and (3) points
(see also Figure H.14). The following sub-sections subsequently describe how these geometries can
be selected and edited. If you do not select any of these three geometry operations, the spatial
AF operation automatically applies to all the data.

Note: Please note that the drawn geometries are not yet persistent, implying that the geome-
tries once drawn cannot be edited yet. Upon pressing the “Esc” button while in editing mode
all drawn geometries will disappear.
DR

Figure H.14: Overview of the available geometry operations in the ‘Spatial Operations’
ribbon

H.4.1 Polygons
Upon selecting “Polygon” from the “Map” ribbon you can draw one or multiple polygons (Figure H.15).
Each polygon point is defined by a single click with the LMB. The polygon is closed by double clicking
the LMB. After drawing the (first) polygon, the available spatial operations for polygons are enabled in
the “Spatial Operations” ribbon. The following spatial operations are available for polygons:
⋄ Crop (section H.5.2)
⋄ Delete (section H.5.3)
⋄ Set Value (section H.5.4)
⋄ Contour (section H.5.5)
⋄ Gradient (section H.5.9)
⋄ Smoothing (section H.5.11)
⋄ Interpolate - only in case samples and a grid/network are available (section H.5.10)
⋄ Copy to samples (section H.5.6)
⋄ Copy to spatial data (section H.5.7) - only for grid coverages

The selected spatial operation applies to all the drawn polygons.

Deltares 536 of 562

 Spatial editor

T
AF
Figure H.15: Activating the polygon operation and drawing polygons in the central map.

H.4.2 Lines
Upon selecting “Line” from the “Map” ribbon you can draw one or multiple lines (Figure H.16). Each
line point is defined by a single click with the LMB. The line is completed by double clicking the LMB.
After drawing the (first) line, the available spatial operations for lines are enabled in the “Map” ribbon.
DR

The following spatial operations are available for lines:

⋄ Contour (section H.5.5)
⋄ Copy to samples (section H.5.6)
⋄ Copy to spatial data (section H.5.7) - only for grid coverages

The selected spatial operation applies to all the drawn lines.

Figure H.16: Activating the line operation and drawing lines in the central map.

Deltares 537 of 562

 Spatial editor

H.4.3 Points
Upon selecting “Add points” from the “Map” ribbon you can draw one or multiple points and assign a
uniform value to them (Figure H.17). Each point is defined by a single click with the LMB. The group
of points is completed by double clicking the LMB. Upon double clicking a popup appears in which you
can assign a value to the points.

T
AF
DR

Figure H.17: Activating the ‘Add points’ operation, drawing them in the central map and
assigning a value to them.

H.5 Spatial operations

The spatial editor supports the following spatial operations (see also Figure H.18):
⋄ Import (section H.5.1) - only for point clouds
⋄ Crop (section H.5.2)
⋄ Delete (section H.5.3)
⋄ Set Value (section H.5.4)
⋄ Contour (section H.5.5) - only for point clouds
⋄ Gradient (section H.5.9)
⋄ Interpolate (section H.5.10) - only for point clouds
⋄ Smoothing (section H.5.11)
⋄ Change single value (section H.5.12) - only for grid coverages
⋄ Merge spatial data (section H.5.8) - only for grid coverages
⋄ Copy to samples (section H.5.6) - only for grid coverages
⋄ Copy to spatial data (section H.5.7) - only for grid coverages

Figure H.18: Overview of the available spatial operations in the ‘Spatial Operations’ rib-
bon

Deltares 538 of 562

 Spatial editor

The sections below provide a description of each operation.

H.5.1 Import point cloud

With the import operation you can import a point cloud for the selected spatial quantity. For this oper-
ation no geometry is required. The import operation is activated from the ‘Spatial Operations’ ribbon
(Figure H.19). Upon importing a point cloud you are asked whether a coordinate transformation should
be applied to the imported dataset (Figure H.20). By default it will be assumed that the imported data
is in the same coordinate system as the model. If not, you can indicate from which to which coordinate
system the data should be transformed. After import the point cloud is added to the operations stack
(Figure H.21). The difference between this importer and importing a point cloud on the project level

T
in the project tree (section H.2.2) is that for this importer the point cloud is directly assigned to the
selected spatial quantity (e.g. model input) instead of being treated as a separate dataset.

AF
Figure H.19: Importing a point cloud using the ‘Import’ operation from the ‘Spatial Oper-
ations’ ribbon
DR

Figure H.20: Option to perform a coordinate transformation on the imported point cloud

Figure H.21: Appearance of import point cloud operation in the operations stack

H.5.2 Crop
The crop operation crops a point cloud or coverage (depending on which one is active). The crop
operation is activated from the ‘Spatial Operations’ ribbon and only available for polygon geometries.
You can control which part of the data should be deleted by using polygons. If you provide a poly-
gon outside the point cloud or coverage, all data will be deleted. For an example see Figure H.22.

Deltares 539 of 562

 Spatial editor

After cropping (part of) the point cloud of coverage the operation is added to the operations stack
(Figure H.23).

T
AF
Figure H.22: Performing a crop operation on a point cloud with a polygon using ‘Crop’
from the ‘Spatial Operations’ ribbon
DR

Figure H.23: Appearance of crop operation in the operations stack

H.5.3 Delete
The delete operation deletes (part of) a point cloud or coverage (depending on which one is active).
The delete operation is activated from the ‘Spatial Operations’ ribbon. You can control which part of the
data should be deleted by using polygons. If no polygons are provided, the total dataset will be deleted.
For an example see Figure H.24. After erasing (part of) the point cloud or coverage the operation is
added to the operations stack (Figure H.25).

Deltares 540 of 562

 Spatial editor

T
AF Figure H.24: Performing an delete operation on a point cloud with a polygon using
‘Delete’ from the ‘Spatial Operations’ ribbon
DR

Figure H.25: Appearance of delete operation in the operations stack

H.5.4 Set value

The set value operation assigns a value to a point cloud or coverage (depending on which one is
active). The set value operation is activated from the ‘Spatial Operations’ ribbon and only available for
polygon geometries or for the total data set if no polygon is provided. By assigning a value, the user
can choose from the following operations:
⋄ Overwrite : overwrites all existing points within the polygon (excluding no data values) with the
uniform value
⋄ Overwrite where missing (only for coverages) : overwrites all missing values within the polygon
with the uniform value
⋄ Add : Adds the uniform value to all existing points within the polygon (excluding no data values)
⋄ Subtract : Subtracts the uniform value from all existing points within the polygon (excluding no
data values)
⋄ Multiply : Multiplies all existing points within the polygon (excluding no data values) with the uni-
form value
⋄ Divide : Divides all existing points within the polygon (excluding no data values) by the uniform
value
⋄ Maximum : Sets all existing points within the polygon (excluding no data values) to the maximum
of its current value and the uniform value

Deltares 541 of 562

 Spatial editor

⋄ Minimum : Sets all existing points within the polygon (excluding no data values) to the minimum
of its current value and the uniform value

For an example see Figure H.26. After performing a set value operation to (part of) the point cloud or
coverage the operation is added to the operations stack (Figure H.27).

T
AF
Figure H.26: Performing a set value operation (e.g. overwrite) on a point cloud with a
polygon using ‘Set Value’ from the ‘Spatial Operations’ ribbon
DR

Figure H.27: Appearance of set value operation in the operations stack

H.5.5 Contour
The contour operation creates a point cloud with a uniform value along a line or polygon (depending
on which one is active). The contour operation is activated from the ‘Spatial Operations’ ribbon. After
drawing the lines or polygons you have to assign the uniform value (argument) and the sampling
interval in m. This spatial operation can be useful to digitalize information from nautical charts for
example. In this case you first have to import the nautical chart as a geotiff (Figure H.28), set the right
map coordinate system (Figure H.29) and then use the contour operation Figure H.30. Sometimes the
samples are created behind the geotiff. Then you can use the context menu on the samples layer in
the Map tree to bring the samples to the front (Figure H.31). After applying the contour operation it is
added to the stack (Figure H.32).

Deltares 542 of 562

 Spatial editor

T
AF
Figure H.28: Import a nautical chart as a georeferenced tiff file
DR

Figure H.29: Set the right map coordinate system for the geotiff

Figure H.30: Performing a contour operation on a nautical chart using lines to define the
contours and ‘Contour’ from the ‘Spatial Operations’ ribbon

Deltares 543 of 562

 Spatial editor

T
AF
Figure H.31: Bring the sample set to the front if it appears behind the nautical chart
DR

Figure H.32: Appearance of contour operation in the operations stack

H.5.6 Copy to samples

This operation converts the currently selected grid coverage to a sample set, which becomes that
starting point of a new subset. If polygons have been drawn, the operation will confine the copy to the
interiors. The operation will not convert missing values to samples. Note that the operation does keep
a reference to the original copied grid coverage; if it is changes by a re-evaluation of the stack, the
changes will affect the output point cloud.

Figure H.33: Applying the copy to samples operation

Deltares 544 of 562

 Spatial editor

T
AF
H.5.7 Copy to spatial data
Figure H.34: Copy to samples operation result

This operation simply clones the grid coverage, starting a new subset with a snapshot of the currently
selected operation output. Similarly to H.5.6, it keeps a reference to the input data and will perform the
clone again upon re-evaluation.
DR

Figure H.35: Applying the copy spatial data operation

Figure H.36: Copy spatial data operation result

Deltares 545 of 562

 Spatial editor

H.5.8 Merge spatial data

Whenever a subset contains a grid coverage as its editing data (after applying e.g. H.5.7) on the same
grid as the main operation set, its result can be combined with the main set by applying this operation,
similarly to the interpolation operation for sample sets, discussed below. Combining the grid coverages
can be achieved with the usual point-wise methods.

T
AF
Figure H.37: Activating the merge spatial data tool from the ribbon
DR

Figure H.38: The merge operation requests a pointwise combination method

Deltares 546 of 562

 Spatial editor

T
AF
Figure H.39: Resulting grid coverage

H.5.9 Gradient
The gradient operation applies a gradient to a point cloud or grid coverage (depending on which one
is active). The gradient operation is activated from the ‘Spatial Operations’ ribbon and only available
for polygon geometries or for the total data set if no polygon is provided. You have to assign the initial
DR

(start) value, the final (end) value and the going to angle (according to the Cartesian convention with 0
degrees is East, 90 degrees is North, etc Note: This is not working properly yet). For an example see
Figure H.40. After applying a gradient to (part of) the point cloud or coverage the operation is added to
the operations stack (Figure H.41).

Figure H.40: Performing a gradient operation on a point cloud with a polygon using ‘Gra-
dient’ from the ‘Spatial Operations’ ribbon

Deltares 547 of 562

 Spatial editor

Figure H.41: Appearance of gradient operation in the operations stack

T
H.5.10 Interpolate
The interpolate operation is the way to get sample set(s) to a grid or network (e.g. coverage). In the
operation stack this means that we are actively switching from working on a point cloud (helping to
AF construct the coverage) to working on the selected coverage (or spatial quantity). The interpolation
is performed on the data within a polygon or polygons (if provided) or all the data (if no polygons are
provided). The interpolate operation can be performed on a single (selected) sample set or on multiple
sample sets. Both methods are discussed below. The methods for interpolation are either
⋄ Triangulation: performs a Delauney triangulation on the sample point set before projecting onto the
grid.
⋄ Averaging: combines sample points within a possible enlarged cell according to an algorithm of
choice. The user can set the search cell expansion factor (rel. search cell size) and a threshold for
the number of sample points within a cell (minimum sample points), see Figure H.42.
DR

Figure H.42: Interpolation Operation options

Seven Cell averaging algorithms can be chosen by the user; see Figure H.43. These algorithms are
explained below:
⋄ SimpleAveraging: the arithmetic mean1 of the samples inside the search area is taken.
⋄ ClosestPoint: the value of the closest sample inside the search area is taken.
⋄ MaximumValue: the maximum value of the samples inside the search area is taken.
⋄ MinimumValue: the minimum value of the samples inside the search area is taken.
⋄ InverseWeightedDistance: the inverse-distance-weighted mean2 of the samples inside the search
area is taken. Contrary to the arithmetic mean, in which all samples contribute equally to the mean,
1
The arithmetic mean is given by:
1
P N
u(x) = N k=1 ui
2
The inverse-distance-weighted mean is given by:

Deltares 548 of 562

 Spatial editor

when using the inverse-distance-weighted average, the samples close to the query point have a
larger contribution to the mean.
⋄ MinAbs: the minimum of the absolute values of the samples inside the search area is taken.
⋄ KdTree: This is an obsolete option, which will be removed in a future release.

T
AF
Figure H.43: Averaging options

By default, the interpolation will only overwrite missing values in the gridded data set. However, if the
grid coverage already contains values, the user may choose to overwrite or combine the data by a
pointwise arithmetic operation.
DR

Interpolate single (selected) set

To perform interpolation on a single sample set, select the sample set (i.e. ‘set1’) in the operation stack
and press ‘Interpolate’ in the ‘Map’ ribbon (Figure H.44). Since no polygon is provided in this example,
all the samples will be interpolated to the grid. Use polygons if you would like to have more control over
the interpolation. After the interpolation the operation is added to the operations stack (Figure H.45).
Please note that after performing the interpolation the workflow in the stack is shifting from the sample
set (i.e. ‘set1’ - which was a side step to construct the coverage) to the coverage (i.e. ‘bed level’).
 PN
 i=1 wi (x)ui , if d(x, x ) ̸= 0 for all i,

PN i
u(x) = i=1 wi (x)

u ,
i if d(x, xi ) = 0 for some i,
1
wi (x) = d(x,xi )

Deltares 549 of 562

 Spatial editor

T
AF
Figure H.44: Performing an interpolation operation on a single sample set (without using
a polygon) using ‘Interpolate’ from the ‘Spatial Operations’ ribbon
DR

Figure H.45: Appearance of interpolation of ‘set1’ to the coverage ’bed level’ in the oper-
ations stack

Interpolate multiple sets

To perform interpolation on multiple sample sets, select the active coverage (i.e. ‘bed level’) in the
operation stack and press ‘Interpolate’ in the ‘Map’ ribbon (Figure H.46). In the popup you can select
which sample sets to include in the interpolation (in this example both). Since no polygon is provided,
all the samples (from the two sets) will be interpolated to the grid. Use polygons if you would like to
have more control over the interpolation. After the interpolation the operation is added to the operations
stack (Figure H.47). Again note that after performing the interpolation the workflow in the stack is
shifting from the sample set (which was a side path to construct the coverage) to the coverage (i.e. bed
level).

Note: Please note that interpolation of multiple sample sets can also be achieved by importing/com-
bining different sample sets into the same set in the stack instead of using two separate sets. In this
case you can just interpolate the single (selected) set.

Deltares 550 of 562

 Spatial editor

T
AF
Figure H.46: Performing an interpolation operation on multiple sample sets (without using
a polygon) using ‘Interpolate’ from the ‘Spatial Operations’ ribbon
DR

Figure H.47: Appearance of interpolation of ‘set1’ and ‘set2’ to the coverage ’bed level’ in
the operations stack

H.5.11 Smoothing
The smoothing operation smooths out (steep) gradients in a point cloud or coverage (depending on
which one is active). The smoothing operation is activated from the ‘Spatial Operations’ ribbon and
only available for polygon geometries or for the total data set if no polygon is provided. You have
to assign the smoothing exponent and number of smoothing steps. The higher the exponent and
the number of smoothing steps, the heavier the smoothing. For an example see Figure H.48. After

Deltares 551 of 562

 Spatial editor

applying smoothing to (part of) the point cloud or coverage the operation is added to the operations
stack (Figure H.49).

T
AF
Figure H.48: Performing a smoothing operation on a point cloud with a polygon using
‘Smoothing’ from the ‘Spatial Operations’ ribbon
DR

Figure H.49: Appearance of smoothing operation in the operations stack

Deltares 552 of 562

 Spatial editor

T
AF
DR

Figure H.50: The cursor for the overwrite operation showing the value of the closest cov-
erage point

H.5.12 Overwrite (single) value

The ‘overwrite (single) value’ operation allows you to edit single values on the active coverage after the
interpolation. The ‘overwrite (single) value’ operation is activated from the ‘Spatial Operations’ ribbon.
There is no geometry required for this operation. Upon selecting the operation from the ribbon a cursor
will become active showing the coverage value closest to the cursor in a tooltipstring (Figure H.50).
Upon clicking LMB a popup appears in which you can overwrite the value of this coverage point Fig-
ure H.51. After applying the overwrite operation it is added to the operations stack (Figure H.52).

Deltares 553 of 562

 Spatial editor

T
Figure H.51: Performing an overwrite operation on a coverage point using ‘Single Value’
from the ‘Spatial Operations’ ribbon
AF
DR

Figure H.52: Appearance of overwrite operation in the operations stack

H.6 Operation stack

The operation stack keeps track of the workflow of spatial operations that you performed. This helps
you to make transparent how you arrived at your ‘final’ dataset without having to save all the inter-
mediate datasets (steps) separately. Moreover, the stack is reproducible and easily editable without
having to start all over again. This section describes the stack workflow (section H.6.1), how to edit
operation properties (section H.6.2), how to enable/disable (section H.6.3), delete (section H.6.4), re-
fresh(section H.6.5) operations, quick links (section H.6.6) and import/export functionality (section H.6.7).

Note: Currently, the stack is saved in the User Interface project upon saving the project. The next time
you open the project, the stack will reappear. The stack is not (yet) saved in a human readable/editable
file.

H.6.1 Stack workflow

Upon performing a spatial operation, the ‘Operations’ panel will open (see Figure H.53) with the op-
erations stack (tree). The stack first shows on which point cloud or coverage you are working (in this
example ‘bed level’). Subesquently, all the operations on this dataset are listed. For each operation
you can inspect what the input, mask (e.g. the geometry used for the operation) and output are for the
operation (Figure H.54). By default the stack continues from the last operation that you performed. If
you wish to work on a different dataset or operation within a dataset, you have to select that dataset or
operation in the ‘Operations’ panel with the LMB.

When working on a coverage, point clouds (or sets) can be used to construct the coverage. In that
case the stack jumps from the ‘trunk’ to a ‘branch’ and the subsequent operations are performed on the

Deltares 554 of 562

 Spatial editor

T
AF
Figure H.54: Input for the operation (top panel), mask for the operation (middle panel)
and output of the operation (bottom panel)
DR

point cloud (see Figure H.53). By selecting the set or coverage in the ‘Operations’ panel you determine
on which dataset you are working. The interpolate operation (section H.5.10) allows you to bring data
from the point cloud (branch) to the coverage (trunk). See also Figure H.53.

Figure H.53: The ‘Operations’ panel with the operations stack. In this example ‘bed level’
is the coverage (e.g. trunk) that is edited. The point clouds ‘set 1’ and ‘set
2’ (e.g. branches) are used to construct the ‘bed level’ coverage.

H.6.2 Edit operation properties

For each operation that you performed the properties (such as the value or ‘Pointwise operation’ of
a ‘Set Value’ operation) can be edited using the ‘Properties’ window (Figure H.55). Note: Please

Deltares 555 of 562

 Spatial editor

T
AF
DR

Figure H.55: Editing the value or ‘Pointwise operation’ of a ‘Set Value’ operation using the
properties panel

note that the mask of an operation cannot (yet) be edited. By editing the operation properties the
operation stack becomes ‘out of sync’ and has to be refreshed for the changes to become active (see
section H.6.5).

H.6.3 Enable/disable operations

You can (temporarily) enable/disable operations by selecting the operation and pressing boxed cross
icon in the stack menu (Figure H.56). Upon disabling an operation the operation will be made grey in
the stack and the operation is not taken into account anymore upon evaluation of the overall result.
The result of disabling an operation is not directly activated. This is indicated in the stack with the
’out of sync’ exlamation mark (Figure H.56). You need to refresh the stack (see section H.6.5) for the
changes to become active.

Deltares 556 of 562

 Spatial editor

T
AF Figure H.56: Disabling an operation using the boxed cross icon in the stack menu. The
operation will become grey. Note the exlamation marks marking the stack
‘out of sync’.

H.6.4 Delete operations

To delete an operation permanently you have to select the operation and either press the cross icon
(Figure H.57) or use the context menu and select delete (Figure H.58). The operation will be removed
from the stack. The result of deleting an operation is not directly activated. This is indicated in the
stack with the ’out of sync’ exlamation mark. You need to refresh the stack (see section H.6.5) for the
DR

changes to become active.

Figure H.57: Removing an operation from the stack using the cross icon in the stack
menu

Deltares 557 of 562

 Spatial editor

T
Figure H.58: Removing an operation from the stack using the context menu on the se-
AF lected operation

H.6.5 Refresh stack

When the stack is marked ‘out of sync’ by exclamation marks, you can refresh the stack by pressing
the ‘Refresh’ button for the changes to become active (Figure H.59). Upon refreshing the stack all the
(enabled) operations in the stack will be (re-)evaluated. Note: Please note that refreshing the stack
can take some time when large datasets are (re-)evaluated!
DR

Figure H.59: Refresh the stack using the ‘Refresh’ button so that all operation are (re-)
evaluated

H.6.6 Quick links

The stack menu contains two quick links to quickly show the original dataset (e.g. where you started
from, Figure H.60) and the end result of the spatial operations (Figure H.61).

Deltares 558 of 562

 Spatial editor

T
AF Figure H.60: Quick link to the original dataset before performing any spatial operations
DR

Figure H.61: Quick link to the output after performing all (enabled) operations

H.6.7 Import/export
Note: Importing and exporting data into or from the stack is still under construction

Deltares 559 of 562

DR
AF
T
 T
AF
DR

+31 (0)88 335 81 88

[email protected]
www.deltares.nl/software
DR
AF
T