D-Water Quality Input File Description
D-Water Quality Input File Description
D-Water Quality Input File Description
T
AF
DR
User Manual
Released for:
Delft3D FM Suite 2023
D-HYDRO Suite 2023
SOBEK Suite 3.7
WAQ Suite 2023
Version: 1.1
SVN Revision: 78284
13 April 2023
D-Water Quality, User Manual
T
AF
DR
Contents
List of Tables vii
T
0.4.2 Convenience options . . . . . . . . . . . . . . . . . . . . . . . . . 5
4 Hydrodynamic data 33
4.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.2 Number of exchanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.2.1 Standard processing for irregular solvers . . . . . . . . . . . . . . . 35
4.2.2 Processing for solvers on regular grids . . . . . . . . . . . . . . . . 35
4.3 Number of additional dispersion and velocity arrays . . . . . . . . . . . . . . 35
4.4 Exchange pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.5 Dispersions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Deltares iii
D-Water Quality, User Manual
T
4.11 Finalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7 Process steering 57
7.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.2 Steering items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
7.3 Data blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
7.3.1 CONSTANTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
7.3.1.1 Special constants . . . . . . . . . . . . . . . . . . . . . 59
7.3.2 PARAMETERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
7.3.3 FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
7.3.4 SEG_FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 65
7.3.5 Multiple copies of substances . . . . . . . . . . . . . . . . . . . . . 65
iv Deltares
Contents
7.4 Finalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
8 Initial conditions 67
8.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
8.2 Old specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
8.3 New specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
8.3.1 Multiple copies of substances . . . . . . . . . . . . . . . . . . . . . 70
8.4 Z-layer models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
8.5 Finalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
T
9 Model output 71
9.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
9.2 Output files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
9.3 Additional output variables . . . . . . . . . . . . . . . . . . . . . . . . . . 73
9.4 Finalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
AF
10 Statistical output
10.1 General . . . . . . . . . . . . .
10.2 Definition of time intervals . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
75
75
76
10.3 Supported statistical procedures . . . . . . . . . . . . . . . . . . . . . . . 76
10.4 Definition of statistical procedures . . . . . . . . . . . . . . . . . . . . . . . 77
10.5 Statistical output files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
10.6 Finalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
11 Annexes 79
11.1 Time tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
DR
Index 89
Deltares v
D-Water Quality, User Manual
T
AF
DR
vi Deltares
List of Tables
List of Tables
1 Groups of ASCII input data for the D-Water Quality input processor . . . . . . 2
2 Supported diagnostic output levels of the D-Water Quality input processor . . 6
2.1 Supported keyword steered options in the D-Water Quality input processor . . 13
T
11.2 Documentation of the binary input files that can be read directly by D-Water Qual-
ity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
AF
DR
Deltares vii
D-Water Quality, User Manual
T
AF
DR
viii Deltares
0 A guide to this manual
0.1 Introduction
D-Water Quality is a generic mathematical model for water quality and ecology. It has two
different parts that work together. It solves the equations for advective and diffusive transport
of substances in water on the one hand and it models the water quality kinetics of chemistry,
biology and physics that influence the behavior of substances and organisms in the water
on the other hand. D-Water Quality is generally applied in waterflow of surface water and
or ground water in any dimension, 1D, 2D-vertical, 2D-horizontal or 3D or a combination of
T
these dimensionalities. Since it is strictly mass conserving with regard to both the transport
of substance and the biological en chemical transformations between substances and organ-
isms, it can be applied to compressible flows (like air) as well and a small number of these
applications are known in the past decades. The vaste majority of applications however is in
incompressible flow like water.
AF D-Water Quality does not compute the flow itself. It is connected to hydrodynamic flow models
to obtain the likely flows in real life situations. Alternatively you may specify a stylistic flow
field by hand yourself. D-Water Quality has been connected to the flow models Delft1D-2D
(SOBEK), Delft2D-3D, Delft-FM, Simona and Waqua and to ROMS, TELEMAC 2D and 3D,
Untrim, ECOM and ShyFem. Because of its mass conserving Finite Volume principles it can
be connected to any water flow model that conserves mass. The mentioned models illustrate
this. They range from Finite Difference models through Finite Volume models to Finite Element
models both on structured and unstructured grids and with different dimensionality
This User Manual concerns the ASCII input processor. With this manual, the user should
be able to make an ASCII input file that ’works’. Additional to this ASCII input, also the
DR
hydrodynamic flow data needs to be present. This is generally done by a coupling program
that may be built into the hydrodynamic model like for Delft1D-2D (SOBEK), Delft2D-3D, Delft-
FM, TELEMAC 2D and 3D and Untrim or that works on the output files of such a model. The
coupling may act on single time steps, calling D-Water Quality as a dynamic link library (dll)
or as a shared library per time step or the coupling may act on finished hydrodynamic results
for subsequent multiple water quality model computations. The Deltares staff supports the
construction of these coupling programs for any mass conserving third party flow model.
Although the manual will allow you to make a D-Water Quality ASCII input file to let the model
’work’, it is generally convenient to have a correct sample input file at hand to start with. Such
sample input files are produced by the Graphical User Interfaces that support the connection
with many of the mentioned hydrodynamic modelling systems. The sample input file can
then be modified according to your needs using this manual. This is especially valuable
for those options that are not supported by the GUI yet. A warning should be given here:
the input file that is described here is generally the output file of the GUI. This means that
your modifications generally do not enter into the GUI again and any modified ASCII file will
generally be overwritten by the GUI if you do not make the precaution to store it in a safe place
and/or under a safe name.
The ASCII input file of the D-Water Quality model can be created and/or modified using a
normal text editor. Be aware however that the D-Water Quality input processor may not un-
derstand tabs and word processor directives. The ASCII input of the D-Water Quality model
is divided into 10 sections that are also distinguishable in the input file itself by section sep-
aration lines. Each section is called an input "group" and each input group is described in a
separate chapter of this manual. Each input group closes with the token: #n, with n the group
number. This closing token may start anywhere on a line like:
#4 ; this is the end of group 4
If D-Water Quality does not encounter the closing token at the right location in the file, it will
Deltares 1 of 95
D-Water Quality, User Manual
Table 1: Groups of ASCII input data for the D-Water Quality input processor
Group Description
T
3 cells, grids, cell properties, volumes
8 initial conditions
9 output specification
10 statistical output
DR
1 Make a set water flow files for water quality simulations with one of the supported hydro-
dynamic models.
2 Import this hydrodynamics into the user interface and generate a simulation with default
substance settings. This step should make an input file for a simulation with 1 substance
‘continuity’ with initial conditions and open boundary conditions of 1.0. Check that also
waste loads with water flow associated with it should have a concentration of 1.0 attached
to the water flow. Choose a safe integration option like option 15. Out should come
1.0. This proofs the mass conservation of the underlying hydrodynamics. Deviations may
occur due to precipitation and evaporation that will likely not be included in your first test
simulations.
3 Decide on the substances and processes to model. Try to select them through the PLCT
(Process Library Control Tool). This tool produces a .sub file with the selected settings.
Import this .sub file into the user interface.
4 Decide on the initial conditions, waste loads, coefficients that have no default value and
decide on the most informative output for your selection.
5 Created a ASCII .inp input file and run the first and second step and make graphs of the
results. This should give no significant problems, at least no problems where you need
this manual for.
6 Modify your input and test alternative settings using this procedure. If you can complete
your job in this way, then that is fine and you do not need this manual further more, since
the GUI does everything for you.
2 of 95 Deltares
A guide to this manual
7 Should you need functionality that is not supported by the GUI, then you may edit the .inp
file manually to use that functionality. That is where this manual comes in.
8 Be aware that you have to save your manually edited file under a different name and / or
at a different location the ensure that the GUI will not overwrite your edited input file. You
may nevertheless use the GUI to run the D-Water Quality model with your edited input file.
That saves you the trouble of determining the command line options to use.
9 You may easily make errors by manually editing your input file. You can inspect the correct
interpretation of your input file by scanning the .lst output file. Search for strings like
‘WARNING’ or ‘ERROR’ if you find the .lst file too bulky to read it in detail.
T
0.3 Glossary
We include here a glossary for several reasons. First, some words will occur frequently in the
text and a quick reference guide could be useful. Second, in the D-Water Quality modelling
terminology some words may have a slightly different meaning than you are used to. Hence it
AF is important to realize their definition. Third, throughout the manual specific terms related to
the model will be introduced. These terms are compiled here for easy reference.
Substance A D-Water Quality state variable. D-Water Quality models the trans-
port of active or transported substances by solving the advection-
diffusion equation numerically. The concentration of inactive or pas-
sive substances is not affected by advective or dispersive trans-
port but only by the water quality processes. The D-Water Qual-
ity processes-library contains water quality processes and additional
transport processes. The concentration of both the transported and
the passive substances can be affected by the water quality pro-
DR
cesses.
Active (substance) Active or transported substances are substances that will be trans-
ported by the flow of water, they thus consist of dissolved and partic-
ulate material in the water column.
Inactive (substance) Inactive or passive substances are substances that are not trans-
ported by the flow of water. Substances that are part of the water
bed or are attached to the water bed are passive substances.
Process Processes are kinetic formulations that apply to substances. They
can be divided into water quality processes and transport processes.
A water quality process is associated with the transformation of sub-
stances into other substances (e.g. nitrification or mineralization) and
it generates one or more fluxes between those substances. A trans-
port process is associated with the redistribution of substances and
it generates one or more velocities or dispersions additional to those
already present by the movement of the water. Common transport
processes are e.g. the sedimentation of particulates or additional dis-
persive transport of e.g. fish by own swimming. A process may also
generate process output. Some processes only calculate process
output, e.g. the calculation of the extinction of light. Other processes
also calculate fluxes between substances.
Process output Process output can be made available for post processing in the
same way as the substances are displayed in graphs and numerical
output files. This is very helpful to identify the value of intermediate
variables like available light at a certain water depth or the sum of all
modeled algae expressed as chlorophyll.
Flux Many processes also compute fluxes as output. A flux is a change
of the mass of a substance per unit of time and of volume as a result
of the specific water quality process (for example the nitrification flux
Deltares 3 of 95
D-Water Quality, User Manual
T
area through which flow and mixing takes place between those ad-
jacent volumes. This is called an exchange and is defined by the
to and from volume number on both sides. Positive flow is from the
from volume to the to volume. Some numerical schemes also re-
quire a from-minus-1 and a to-plus-1 cell or volume number to allow
AF Segment related and
exchange related
for higher order accurate numerics.
Process input and process output is divided into segment/volume
related and exchange related information. Segment related informa-
information tion is defined for each segment of the schematization (e.g. param-
eters or concentrations). Exchange related information is known for
each exchange area of the schematization (e.g. flows or additional
velocities).
Exchange area The contact surface of two linked computational volumes (or seg-
ments).
Constant Input parameter that does not vary in time or in space.
DR
Parameter Spatially distributed input parameter that does not vary over time.
Segment function Spatially distributed time function (usually a large and binary file cre-
ated by other software) that contains information for a spatially dis-
tributed model parameter that varies over time.
Solver Part of the computational core that solves the Advection Diffusion
Equation (ADE)
4 of 95 Deltares
A guide to this manual
T
The D-Water Quality input file with more or less this structure dates back to 1986 and old files
are still read with minor or no adaptations with the present input processor. Unfortunately you
still see some option numbers in the input file as remnants from this past. They function as
switches and are not so clear. You need this manual to identify their meaning. Increasingly
AF more we are changing those option numbers into meaningful keywords but we also want to
remain compatible with older input files. So this manual aims to document the currently most
modern version of the input processor and many of the outdated constructs are still supported,
but are not explained in this manual any more.
ment. You can use a comment line as header for the lines that follow as a kind of column
headers. You can also continue information with a comment on the same line to indicate
what the row is meant for.
⋄ You may insert any amount of blank lines you need for readability.
⋄ Character input like names/IDs can be inserted in the file without further quotes or double
quotes. Only if the character string contains embedded blanks, it should be surrounded
by single or double quotes. A string variable surrounded by single quotes may contain
double quotes. A string variable surrounded by double quotes may contain single quotes.
A string variable surrounded by any quotes may contain comment characters.
⋄ Integers consist of numbers 0-9 only, optionally directly preceded by a sign.
⋄ Floating point variables may be specified e.g. as -23.48 or as 0.25E+04 or as 3.14e2.
⋄ Any keywords to steer input processing are always required in CAPITALS.
Deltares 5 of 95
D-Water Quality, User Manual
Table 2: Supported diagnostic output levels of the D-Water Quality input processor
Level Output
Level 2 grid layouts, dispersion IDs and fields, boundary types, waste load types,
T
names of constants, parameters, functions, segment functions
Level 5
any variable time step specification
6 of 95 Deltares
1 Identification, selected substances
This is the first group in the input file. The following example of the input for this group is
produced by the user interface and reads like:
T
; PRINT_OUTPUT_OPTION_4
; Index Name
1 'OXY'
2 'CBOD5'
3 'SOD'
A valid example for the first line is: 200 132 ';'
Deltares 7 of 95
D-Water Quality, User Manual
vided since, but they either are compatible with previous structures, or their presence is
indicated by the presence of certain keywords that precede the new functionality. The de-
fault version number is 0.0, but that will result in input file reading that deviates significantly
from present days input. The version number that corresponds with the contents of this
manual is 4.91.
⋄ PRINT_OUTPUT_OPTION_4
The string is immediately followed a 1 character integer that refers to the level of diagnostic
output as was explained in table 2. The default output level is -1. This level, like level 0,
only produces the most basic information.
T
1.3 Model title and calendar date string
The next input for the input processor should be 4 strings that form the model title. They are
also displayed on printed output and in binary files. These strings should be present, so in
case you do not want to use the option you have to provide e.g. 4*' '. The strings are
AF each 40 characters long. If longer strings are provided, they are truncated. In the example
at the head of this chapter it can be seen that the strings may contain embedded comment
characters and double quotes and blanks if surrounded by single quotes.
There are 2 different areas within these 4 title strings that have a special meaning:
⋄ MASS/M2
If this token is present in the character positions 34-40 of the 3rd title string, then several
programs assume that typical waterbed related substances are expressed in mass per
m2 , rather than in mass per grid cell which was the unit before January 2011. You should
not provide this information here. You should however be prepared that the D-Water Qual-
ity system overwrites the last 7 characters of your 3rd title string.
DR
8 of 95 Deltares
Identification, selected substances
T
6 ; number of passive substances
Note: Because the passive substances are not transported, it is impossible to compute
a steady state spatial concentration pattern due to stationary transport patterns for them.
This is why passive substances are not allowed for the few steady state solvers within D-
Water Quality. The relevant steady state solvers have numbers 17 and 18. The steady state
AF
1.5
solvers 6 - 9 are obsolete and should not be use any more.
Substance names
For each substance a name should be provided. A substance name is a string of 20 char-
acters that serves as the ID of the substance. The substance name / ID should be unique.
If a blank ' ' is given, D-Water Quality will make the name `Substance n' with n is the
substance number.
The processes library recognizes substances from their ID, so the ID should correspond ex-
actly with the corresponding ID in the processes library. Here the use of the the Graphical
DR
User Interface, GUI pays. Substances selected by the user interface enter into an input file
created by the user interface automatically with the correct ID. It is nevertheless possible to
add additional substances with different names. Because they are not recognized by the pro-
cesses library, they are not subject to water quality processes, but they can e.g. be used as
tracers in the model.
The sample input shows a sequence number and the substance ID. The user interface will
make an input file with all substance IDs in order of the sequence number. You can change
this order, by changing the sequence numbers. You are however not allowed to use the
same sequence number twice and all passive substances should have the highest sequence
numbers (the transported substances loop from 1 to NOSYS in the substances array, the
passive substances loop from NOSYS+1 to NOTOT). Input can look like:
You will note how the comments are used to enhance readability of the data. You will also
note that it does not matter whether the numbers of transported and passive substances are
mentioned on one line or on different lines. It also does not matter where the information is
placed on the line, only the order in which the information appears matters.
Deltares 9 of 95
D-Water Quality, User Manual
All these instances should basically share the same processes in the processes library, al-
beit with optionally different reaction coefficients. This could be done by just specifying their
IDs like above, but that becomes less practical if 100 sediment fractions are required or 57
conservative tracers to monitor the fate from 57 waste fluxes or the specification of 50 algae
species in mutual competition. For that reason a functionality has started to appear from 2011
on that is called multiple substances.
The input is simple:
T
; Index Name
2 OXY ; Oxygen in mg/l
1 CBOD5 *5 ; 5 instances of CBOD5
3 SOD *5 ; 5 instances of Suspended Sediments at the bed
Note:
AF ⋄ The passive substance at the water bed is the last substance.
⋄ If 2 plus 1 substances are specified respectively then only for this three substances the
ID’s need to be specified.
⋄ There should be a space between the ID and the ‘*n’ token.
⋄ There should be no space between ‘*’ and the 1-3 digits that specify the amount.
⋄ Due to the multiplication, 1 + 2*5 = 11 substances are finally modeled, 5 of them are
passive.
⋄ The substances turn out to be automatically named CBOD501 - CBOD505 and SOD01 -
SOD05.
⋄ If two substances share fluxes and have the same multiplicity, then it is automatically
DR
assumed that the single substances with the same number are coupled.
1.6 Finalization
This part of the input file is finalized with the #1 end of first data group indicator.
10 of 95 Deltares
2 Timers, integration, monitoring
This is the second group in the input file. The input for this group may read like:
T
BAL_NOLUMPPROCESSES
BAL_NOLUMPLOADS
BAL_NOLUMPTRANSPORT
; ddhhmmss
0123000 ; simulation start time
25123000 ; simulation stop time
AF ;
0
0000500
7
;
;
constant time step
time step size
⋄ timer strings
D-Water Quality timers are integers. This helps avoiding round-off errors. It is however
more convenient to tell D-Water Quality that it has to stop simulation ’after 31 days’, rather
than ’after 2678400 seconds’. For this reason you may tell D-Water Quality that you will
provide input in DDHHMMSS format. This allows you to specify 31000000 for 31 days. D-
Water Quality is still using 32 bits signed integers for its timers and thus you may not spec-
ify a higher time then 2147 days 48 hours 36 minutes and 48 seconds, since 2147483648
Deltares 11 of 95
D-Water Quality, User Manual
equals 231 . This limits your specification to 5 years and 10 month. This may change
in near future, but you can in the mean time use the alternative of specifying times in
YYDDDHH format for a maximum of 231 seconds = slightly over 68 years. You must give a
timer string for both the system timer and for the auxiliary (processes) timer. Your choice
will hold for the time integers that you specify throughout the complete input file.
The times that you specify this way are in system time units. If you want to know where
they are located on the calendar, then you have to add them to the reference time as
mentioned in the reference time string. Please be aware that D-Water Quality assumes
365 days within one year of its system time units. The specification in system time units
can thus mean a shift of a day per 4 years in the date and time that may be printed. This
T
can be avoided. At many locations in the D-Water Quality input file you can alternatively
provide a calendar string instead of an integer. This only works if you also did specify a
reference time. D-Water Quality will then subtract the reference time and date from your
specified time and date and use the result in seconds as the system time of you input.
The following strings are valid timer strings:
AF DDHHMMSS
⋄ ⋄ ⋄ ⋄ ⋄
ddhhmmss
YYDDDHH
yydddhh
' '
The blank character indicates that just the system timer is used. If one timer string was
set to DDHHMMSS, then only ' ' or DDHHMMSS are allowed for the other string. If one
timer string was set to YYDDDHH, then only ' ' or YYDDDHH are allowed for the other
string. So if both timer strings are not blank, they should be equal.
DR
12 of 95 Deltares
Timers, integration, monitoring
Table 2.1: Supported keyword steered options in the D-Water Quality input processor
T
cells and to prevent dispersion through thin
dams.
Deltares 13 of 95
D-Water Quality, User Manual
14 BAL_NOSUPPRESSSPACE To be documented.
1
BAL_SUPPRESSSPACE
15 BAL_NOSUPPRESSTIME To be documented.
a
BAL_SUPPRESSTIME
T
16 SCHEME15_UNSTRUCTURED 3rd dimension not treated as layered
SCHEME15_STRUCTUREDa Also iterates the 3D model dimension rather
than a simple double sweep inversion.
AF 17 ANTIDIFFUSION
NO-ANTIDIFFUSIONa
Option of scheme 21 and 22
To be documented.
From the table 2.1 it can be seen that often also the negations are generally recognized. They
are of less importance, because they are the default setting. You may use as many of the
keywords mentioned as you need and their order of appearance is generally not important.
DR
Keywords 4, 5 and 6 are mutually exclusive like the two keywords that negate each other. In
such a situation the last of the mutually exclusive keywords prevails.
14 of 95 Deltares
Timers, integration, monitoring
D-Water Quality simulation. You will also note that the remainder of the D-Water Quality
input file can remain the same until the specification of the initial conditions.
4 You insert initial condition values for all D-WAQ PART substances in group 8 of the D-
Water Quality input file. The most obvious value to enter is 0.0 here.
You will note that you can now run a joint D-Water Quality and D-WAQ PART simulation. You
will also note that the D-WAQ PART substances appear in the monitoring file, the <.map> file
and the <.his> file. Moreover, the D-Water Quality model concentrations are now available
to the D-WAQ PART simulation and the D-WAQ PART model concentrations are available to
T
the D-Water Quality water quality processes.
You may wonder why you should model some substances with a particle tracking model and
other substances with a Finite volume advection- diffusion solver in D-Water Quality. The
reason is that the grid cell, the Finite Volume, is the smallest unit that D-Water Quality distin-
guishes. If you are using a grid that is not so fine, then point sources will spread immediately
AF
over the grid cell, whereas in reality it might take up to a day before an initially released patch
of dye has grown sufficiently large that the Finite Volume ADE solver can take over the com-
putation of the result. To avoid an unrealistic initial spreading you may consider to model
the initial spreading process using the particle tracking option and continue the modeling af-
terwards using the Finite Volume solver. For this aim the D-Water Quality take over time or
delay time that was mentioned in the D-WAQ PART manual as ”no longer being supported“ is
revived again. That works as follows:
⋄ If you name a substance in the D-WAQ PART part of the simulation exactly identical to
a corresponding substance in the D-Water Quality part of the simulation, but with an ad-
ditional ’p’ just behind the D-Water Quality name, then the interface between both knows
that these two substances belong to each other.
DR
⋄ If you specify a D-Water Quality take over time, generally in the orde of 1 day, in the D-
WAQ PART input file, then all particles that did stay longer than the specified take over time
span in D-WAQ PART are removed from the D-WAQ PART simulation and are migrated
towards the D-Water Quality simulation as a contribution to the concentration in the grid
cell where they were. D-Water Quality will transport this mass further with its Finite Volume
solvers.
⋄ If you add both results, you will see the advantage of the efficient and robust mid-field and
far-field modeling with D-Water Quality and you will note the sub grid patch and concen-
tration patterns that are modeled with D-WAQ PART for the initial period just after release.
This is just one example of the benefits of the joint simulation of D-Water Quality and D-
WAQ PART. Other examples are:
⋄ model spilled oil patches with D-WAQ PART and let the entrained and emulgated oil mi-
grate from the D-WAQ PART side to the D-Water Quality side and use the results there
to identify the exposure of sensitive receivers like fish and coral reefs to the dispersed oil
fractions.
⋄ use the D-WAQ PART ’time in the system’ variable per particle to determine the shift from
fish eggs to larvae and juvenile species and let the thus modeled species get their food
from the concentration of algae, zooplankton or other particulate organic carbon that is
modeled by D-Water Quality.
Deltares 15 of 95
D-Water Quality, User Manual
T
Please be aware that an error is generated even if you only use other separation charac-
ters between the digits of the date. The parser is very strict.
⋄ The time step option switch.
There are 2 values allowed:
AF 0 indicating a constant time step size
1 indicating a time varying time step size
⋄ The information on the time step of the integration
In the case of a constant, an integer is required in system units or in DDHHMMSS style
⋄
or in YYDDDHH style.
In the case of a time series the following information is expected:
⋄
16 of 95 Deltares
Timers, integration, monitoring
That many integer sequence numbers of the computational volumes that form together
this area.
Note: The DIDO grid manipulation tool of the Graphical User Interface is able to make
ASCII files with monitoring areas that can directly be included into the D-Water Quality
input file. You may need to edit the file because it is using # as comment character while
T
you may use ;.
Note: A special feature is the "moving monitoring point" for which the location is not fixed
in time. The monitoring point can be used to compare model data with moving measure-
ment devices like drifters or vessels sailing a trajectory. This is a single segment obser-
vation point with a name starting with "MOVING", if there exists a function (see process
AF
parameters) with exactly the same name then the segment number of the observation
point will be set with the value of the function evaluated at the current time. The value of
the function is the segment number. Since the value is discrete one should use only block
functions to specify a moving monitoring point. If there is no observation for a certain pe-
riod a value of 0 can be specified. For this period the output of the moving monitoring point
will be a missing value. The segment number in the specification of the monitoring point
should be given but is not used. To create a list of segment numbers from coordinates
is not trivial. Fortran code is available to create the function from coordinates for Delft3D
kind of grids.
Example of a function to specify a moving monitoring point called MOVING_Ferrybox:
FUNCTIONS MOVING_Ferrybox
DR
BLOCK DATA
2012/01/01-00:00:00 0
2012/01/22-08:24:00 2207
2012/01/22-08:25:00 2206
2012/01/22-08:26:00 2206
...
...
2012/01/22-18:21:00 2091
2012/01/22-18:22:00 0
2013/01/01-00:00:00 0
⋄ an integer to indicate if monitoring transects are used: 1 means "yes", 0 means "no".
Deltares 17 of 95
D-Water Quality, User Manual
the integer number of exchange surfaces that together form this monitoring transect.
⋄ ⋄
That many integer sequence numbers of the exchange surfaces that form this transect.
Note: Unfortunately the DIDO grid manipulation tool does not support monitoring tran-
sects. This may make it very tedious to specify transects, because you have no easy
access to the values of the numbers of the interfaces between the different computational
volumes if they are produced by a hydrodynamic model.
T
1 ; Use monitoring locations/areas
3 ; nr of monitor locations and areas
'ObsPoint 1' 1 ; Just a single segment
3548
'ObsPoint 2' 1 ; Just a single segment
AF 4352
'ObsArea 1' 5 ; Use 5 consecutive segments
3891 3892 3893 3894 3895
It is the responsibility of the user to ensure that the output timers coincide with an integer
18 of 95 Deltares
Timers, integration, monitoring
multiple since start of simulation of the least common multiple of all transport and water quality
time steps that are used. This is an integer multiple of the transport time step if that is used
also for water quality. If (some) water quality processes are computed with a longer time step,
then it is an integer multiple of the longer time step.
2.7 Finalization
This part of the input file is finalized with the #2 end of second data group indicator.
T
AF
DR
Deltares 19 of 95
D-Water Quality, User Manual
T
AF
DR
20 of 95 Deltares
3 Grid and values of the volumes
This is the third group in the input file. The following example of the input is derived from a
small model for an advisory project.
T
INCLUDE ../model-input/grid_layout.dat
END_MULTIGRID
;
INCLUDE '../hydro/hyd3g/com-hyd3g.atr'
; volumes
;
-2 ; first volume option
'../hydro/hyd3g/com-hyd3g.vol'
;
#3 ; delimiter for the third block
D-Water Quality used to produce two types of output files for history and map data: the plain
binary files and the self-descriptive NEFIS files. Neither of these files contain any information
on the shape of the grid. To visualise the results you always need an extra file or files that
contain the grid information.
If you specify a WAQGEOM file, which is produced by various hydrodynamic models such as
Delft3D-FLOW D-Flow FM or SOBEK. by means of the UGRID option in group 3, the model
will write NetCDF map and history files. Be sure to switch on NEFIS/NetCDF output options
in group 9.
If the first word in this section is not UGRID, the option is skipped.
Deltares 21 of 95
D-Water Quality, User Manual
volumes. Although this ordering often exists, it is no requirement. A few of the D-Water Qual-
ity advection diffusion solvers require a matrix type of topology of the computational grid, but
most allow a free ordering.
There is however one limitation. If the model is 3-dimensional, then D-Water Quality assumes
that the first n computational volumes are located at the top and form the water surface with
incoming solar radiation and with reaeration of oxygen and CO2 . D-Water Quality also as-
sumes than the last computational volume number of a water column is located at the water
bed and either interacts with the bed or features inactive substances laying on the bed. In
between it is assumed that computational volumes that are lower in the water column have
a higher sequence number. The vertical vector and numbering is positive in the downward
T
direction. This is unlike many hydrodynamic models. The D-Water Quality preference stems
from the convenience that the first n computational volumes describe the complete spatial
coverage of the model. If we would have numbered the other way around then, in models
with fixed layer depths, the first few wet computational volumes would contain the few deep
cells in gullies and the full extent of the model area is only visible by inspection of the last n
3.3
AF computational volumes, but where does this start in the array space?
Grid information
The base grid is the linear array of computational volumes of D-Water Quality. It is convenient
to distinguish other grids as well. It can be useful to distinguish the segments just above the
bed to give them bed related coefficients etc. It can also be useful to distinguish the segments
at the water surface etc. Furthermore, the D-Water Quality model is not limited to the water
phase, also a number of computational volumes in the bed can be distinguished. Often the
schematization of cells in the bed can be much coarser than in the water column, because
transport in the layered bed is assumed to be limited to vertical transport only.
DR
In the optional MULTIGRID section of the input, you are able to define a number of additional
grids and refer to them later on by their name. If the keyword is not used, then there is only
one grid, the base grid. In our sample input file the MULTIGRID information is included from
a file. That file contains e.g. the following information:
ZMODEL NOLAY 13
SUBGRID 'water-grid'
INCLUDE '../model-input/water-grid-ag01.dwq'
BOTTOMGRID 'sediment-grid'
REFERENCEGRID 'Base grid'
INCLUDE '../model-input/bottom-grid.dwq'
BOTTOMGRID 'sediment-zone'
REFERENCEGRID 'sediment-grid' 25*1 60*2 25*3
BOTTOMGRID 'sediment-default'
REFERENCEGRID 'sediment-zone' 3*1
At this location a number of optional keywords is supported. They are listed in table 3.1.
22 of 95 Deltares
Grid and values of the volumes
Keyword Description
T
MULTIGRID Starts the definition of multiple grids.
ZMODEL The model has horizontal layers and the bed may be
located in different layer positions at different hori-
zontal locations.
AF SUBGRID A sub-grid will be defined.
In the sample input file the model is defined to be a z-layer model, so it has horizontal layers
at fixed depth. The number of layers is given as 13. It could be possible that D-Water Quality
is able to identify the number of layers from its own, since the layers are full in this case (13
layers of 110 cells each). To avoid unambiguity it is good to define the number of layers here.
Then 5 different grids are defined. Finally the numbers of layers in the bed are defined.
Deltares 23 of 95
D-Water Quality, User Manual
that the new grid may be coarser than the old grid (have less cells, so the highest cell number
then is lower than 1430 in our case), but can never be finer. Given the hydrodynamic grid
as the base grid, the DIDO grid manipulation tool of the Graphical User Interface is able to
make ASCII aggregation files that can directly be used in the D-Water Quality input file as grid
mapping. You may need to edit the file because it is using # as comment character while you
may use ;.
To define new grids, the following information is expected in exactly this order:
⋄ A unique string with the name / ID of the additional gridindexGrid!ID that is created
⋄ One of the following optional keywords:
T
NOLAY followed by an integer.
⋄
This specifies the number of layers in the grid that is created. If absent, D-Water Qual-
ity assumes that the new grid has as much layers as the grid it is referring to.
REFERENCEGRID followed by an ID of an already created grid.
⋄
The new grid will clone this reference grid. If absent the base grid will be used as the
AF reference grid for this new grid.
⋄ The mapping data from the reference grid to the newly created grid in one of the following
ways:
AGGREGATIONFILE followed by a DIDO aggregation file name.
⋄
The DIDO file maps the reference grid towards this new grid. Because DIDO works on
the hydrodynamic grid, the reference grid in this case will almost always be the base
grid. Since DIDO only works on one layer, it will only contain the aggregation of one
layer.
as many integers as the reference grid has computational cells, each indicating the
⋄
cell number of the newly created grid that is containing the corresponding cell of the
DR
reference grid.
We have defined 3 BOTTOMGRID grids. That is a bit much since there is only one real bottom
grid. The D-Water Quality input processor assumes that the first time a BOTTOMGRID is
defined, that this grid should be considered as the bottom grid. It also tells so in output
24 of 95 Deltares
Grid and values of the volumes
warning statements. In our example this is the sediment-grid with its 110 cells, so one
bed-column underneath each water column.
T
that will be distinguished. This amount of sediment layers will appear underneath the
water at all of the locations of the bottom grid.
⋄ the INPUTGRID keyword
This keyword should be followed by an existing grid name / ID.
Then a number of integer values should follow, equal to the number of grid cells in the
AF selected input grid. Each value tells D-Water Quality that that sediment column of that
grid cell has as many layers as that integer amounts. In our example we mentioned
the sediment-zone grid as the input grid. In this way the cells from the bottom grid
have been grouped in zones, that each have an equal number of sediment layers. In our
example the zone 1 has 10 sediment layers, zone 2 has 8 sediment layers and zone 3 has
5 sediment layers. What D-Water Quality will do is the following:
All cells of the INPUTGRID (3 on our case) get their value (10, 8 and 5 in our case)
⋄ ⋄
Because the input grid is not the bottom grid (that is the sediment-grid in our
case), the grid that is used as reference grid of the INPUTGRID get their values (all
110 in our case) based on the mapping process of the input grid on to the reference
grid of that grid.
DR
This procedure continues until the bottom grid is reached and then the procedure
⋄
stops. So this allows also for nested zonations, that could be useful for different rea-
sons.
This construction allows an easy way to:
define the number of layers in the sediment columns for the bottom grid:
⋄
Note: that it is easy to create the sediment zonation using the DIDO-ASCII aggregation files
with a graphical user interface. Once the zonation has been done, you can easily specify
for each zone a separate value by using the zoned grid as input grid. We will meet that
construction also later on in the input file where process constants and other process variables
and where initial conditions have to be set, depending on a certain zonation of the model area.
Deltares 25 of 95
D-Water Quality, User Manual
If this keyword is used, the next information should be in the form of an attributes file. So,
typical use is:
T
BOTTOMGRID 'bottom'
REFERENCEGRID 'Base grid'
BOTTOMGRID_FROM_ATTRIBUTES
INCLUDE 'generated-file.atr' ; attributes file as generated by the hydrodynamic model
3.6
AF SUBSTANCE_PROCESSGRID keyword
This keyword has to do with the process decomposition features in D-Water Quality. It is
possible to compute a subset of the substances on a coarser grid than on the base grid of the
D-Water Quality simulation. This option will
⋄ transport the selected substances on the finer base grid
⋄ at the time the processes should work those substances are averaged to the coarser grid
⋄ the processes will be conducted on the coarser grid
⋄ the resulting mass on the coarser grid will be subdivided over the finer base grid using
their proportional weighting before the process step
DR
This option is especially valuable if the water quality kinetics are expensive to compute and if
they can be grouped into model zones that more-or-less behave identical with respect to the
water quality processes. The aggregation and disaggregation steps are fully mass conserving,
so the whole procedure remains fully mass conserving and the substances remain transported
on the finer base grid.
The procedure is triggered by the SUBSTANCE_PROCESSGRID keyword. Then one of the
following options should come:
⋄ the ALL keyword
This indicates that all substances will get their processes evaluated on the grid that will be
selected.
⋄ a list of substance IDs
This will select the indicated substances to operate on the grid that will be selected.
Finally the ID of an already earlier defined grid should follow. This will make the selected
substances to get their process kinetics on the coarseness of the selected grid. Again, it is
easy to create a zonation of the grid for this aim, using the Graphical User Interface and the
DIDO tool.
26 of 95 Deltares
Grid and values of the volumes
⋄ at the time the processes on the substances should work, they are invoked
⋄ next transport steps will be set on the finer transport time scale and so on.
This option is especially valuable if the water quality kinetics are expensive to compute and
if they can be grouped to joint coarser time steps. There is also a reverse reason for using
this procedure. It can be required to model the transport of substances with a relatively fine
time step of say 10 seconds to preserve accuracy of spatial transport patterns. Water quality
processes can however easily be evaluated every half hour. This option does that job.
⋄ The procedure is triggered by the PROCESS_TIMESTEP_MULTIPLIER keyword.
T
⋄ Then one out of the following two options should come:
the ALL keyword
⋄
This indicates that all substances will get their processes evaluated on the coarser
time step.
AF a list of substance IDs
⋄
This will select the indicated substances to operate on the coarser time step.
⋄ Finally an integer should follow that specifies the selected multiplier on the transport time
step for the selected
D-Water Quality automatically sets the time step of the processes that act on the mentioned
substances to the required time step for the substances. The default multiplier for the not
mentioned substances is 1. This may lead to inconsistencies if the process acts between
two substances that have different time step multiplier. These inconsistencies have been
dealt with for the two most commonly applied sets of substances on different time scales,
DR
the BLOOM module for algae species competition and the CHARON module for equilibrium
chemistry minimizing Gibbs free energy. Their time step size will overwrite any specified time
step mutiplier of this section. It is generally safe to choose for all modelled substances a time
step multiplier that is the same, e.g. 30 if you would want to model water quality with time
steps of half an hour and transport of substances with 1 minute. A common time step size for
the BLOOM algae competition process is 1 day.
Deltares 27 of 95
D-Water Quality, User Manual
⋄ The integer ’1’ indication that information will follow in this file.
⋄ The integer ’2’ that is the outdated equivalent of the NONE keyword.
For the options ’-1’, ’0’ and ’1’ two integers should follow:
⋄ nx
An integer specifying the horizontal amount of grid cells to be printed. If a zero is specified,
the printed grid layout will NOT be used. If a positive integer is specified, lines with that
many values (of 15 positions each) will be produced in the output file.
⋄ ny
T
An integer specifying the vertical amount of grid cells to be printed. If nx was non zero
and ny is zero, then printed output is NOT used.
For options ’-1’ and ’1’ the following follows in the ASCII file, for option ’0’ in the binary file.
AF ⋄ ny lines with nx integers
The integers refer to the sequence numbers of the computational volumes. A zero in-
dicates that a blank field should appear at that location in the printed grid. The same
segment number may appear multiple times in the matrix.
28 of 95 Deltares
Grid and values of the volumes
property values for all properties is from 0 to 9. The presently implemented 4 properties are
given in table 3.2.
T
2 0 Volume is both at top and at bottom of the water column.
This holds for all volumes of a depth averaged model.
1 Volume is at top of the water column
2 Volume is neither at top nor at bottom of the water column
AF 3 Volume is at the bottom of the water column
If the first attribute is not set, then D-Water Quality sets it at the default value of 1 for the
whole model area. If the second attribute is not set, then D-Water Quality sets it to 0 (depth
DR
At the moment only the properties 1 and 2 are generally provided through the input file. So
the choice is providing them separately or providing only one of them on the one hand or
providing them jointly on the other hand. Joint properties may look like:
Deltares 29 of 95
D-Water Quality, User Manual
In general the hydrodynamic models with a supported interface with D-Water Quality all pro-
duce the required property information in a file that can just be included in D-Water Quality
input processing without further adjustments by the user. The user may edit this file if the wa-
T
ter quality processes in almost dry cells require that these cells are manually excluded from
the computation. Then changing of the property of those cells to zero will do to xclude the
cells.
characteristic distances between the volumes form a second set of coefficients, they complete
the input for the advection - diffusion equation. It could be well argued to locate all of this input
into one input group. That is done, they are in input group 4. For historical reasons there is
however one exception and that are the volume values of the segments / computational cells.
They are contained in this group 3. Volumes distinguish themselves from other hydrodynamic
input in a number of ways:
⋄ There are as many volume values as there are volumes. This number is called NOSEG
and is equal to the amount of active cells in the base grid. The other hydrodynamic input
has as dimension the number of exchange surfaces between volumes. This dimension is
called NOQ. For 1-dimensional models NOQ is generally of the same order (but generally
not equal to) NOSEG. In 2 dimensional models NOQ is generally about 2 times NOSEG and
in 3-dimensional models about 3 times NOSEG.
⋄ The volumes are given at certain times. They give the exact volumetric value at that time.
All other hydrodynamic input describe the average value of the coefficients during the time
step. By convention the time stamp of the records of the other coefficients is the start time
of the time step of their functioning, that runs from that value to the time stamp of the next
record.
⋄ D-Water Quality can compute with time steps that are smaller than the time steps in the
hydrodynamic files. Those time steps are then subdivided. To ensure mass conservation
the volumes in between two time stamps are interpolated. Because the other hydrody-
namic information is assumed to count for the whole time step, they are not interpolated
but taken constant during the hydrodynamic time step. This procedure is furthermore
called a block function contrary to the linear interpolated volume function.
The volumes are read through the standard input procedure for hydrodynamic data that is
described in the Annexes. Per computational volume (or segment) one value is read. One
scale value applies. As seen from the sample input file at the start of this chapter, this part of
30 of 95 Deltares
Grid and values of the volumes
the input is most commonly limited to ’-2’ and the name of the volumes file that was generated
by the hydrodynamic model. Also input of ’-4’ and the name of a MULTIPLE_HYD file is
regularly used. Be aware that the amount of values that is expected per time step is exactly
equal to NOSEG, the number of active cells in the base grid. The value of the time token of
each record in the time varying setting should be consistent with the integration timers and
output timers.
3.11 Finalization
This part of the input file is finalized with the #3 end of third data group indicator.
T
AF
DR
Deltares 31 of 95
D-Water Quality, User Manual
T
AF
DR
32 of 95 Deltares
4 Hydrodynamic data
This is the fourth group in the input file. This group may read like:
T
0 ; number of additional velocity arrays
4.1 General
Group 3 of the input file already contained information that is associated with the schemati-
zation of the model and the water flow. It contained the number of computational volumes /
cells / segments (names that are all equivalent). It also contained a description of the input of
the (time series) of the volumes in m3 for each of these segments. Group 3 also contained
information on the properties of these cells / segments ( dry or wet, at the top, at the water
bed or in the middle ).
In group 4 of the input file this information on model schematization and hydrodynamic infor-
mation is continued with flows across the exchanges and other transport related information.
Most of the time, hydrodynamic input will be substantial and will be generated by hydrody-
namic models. For these situations the input as given in the example at the start of this
chapter is typical and it is also the minimal input required. We will run through this example
input here to explain the different input items. There are much more additional options per
input item than mentioned in this explanation and they are discussed in detail in the sections
that follow in this chapter.
it has exchange interfaces in three directions. This means that 2 separate horizontal
directions exist. Models with unstructured grid generally have only one total number
of exchanges for direction 1 and zero for the number of exchanges in direction 2.
It is a 3-dimensional model. Depth averaged models have zero for the number of
⋄
Deltares 33 of 95
D-Water Quality, User Manual
The model is apparently using a grid that consists of a full matrix (with many zero’s at
⋄
locations in the matrix with dry entries). This can be inferred from the exactly equal
number of exchanges in both horizontal directions. For models on matrices of grid
cells with only the active cells and active exchanges mentioned, the number of active
exchange surfaces in the two horizontal directions is generally not exactly equal.
One layer of the model apparently has 2800 grid cells. This is the difference between
⋄
the number of exchanges in one horizontal direction and in the vertical direction. There
is one layer of exchanges less in the vertical, because between n layers there are only
n - 1 interfaces.
It is a 40 layer model because the number of horizontal exchanges in one direction
⋄
T
divided by 2800 is exactly 40.
D-Water Quality also makes these inferences, but it also allows for the direct specification
of the number of layers and it does not require full matrices of input, it even does not
require a structured grid.
⋄
AFThe number of additional dispersion arrays
D-Water Quality has constant dispersion coefficients (diffusion coefficients that account
for the turbulent diffusion and the additional mixing at coarser grids additional to molec-
ular diffusion) in the three mentioned exchange directions. You can furthermore specify
additional spatially varying dispersion coefficients per exchange surface. You do so by
specifying a non-zero the number of additional dispersion arrays here. You might think
that you need to do so if you want to use the vertical diffusions that are generated by the
turbulence model of the hydrodynamic model. That however is not the case. The hydro-
dynamic model will produce the vertical diffusions per cell and not per exchange. In group
7 of the input file you will specify the vertical diffusion file that is produced by the hydro-
dynamic model. There also the ’process’ will be switched ’on’ that creates an additional
DR
diffusion array and puts the vertical coefficients therein. You just specify zero here.
⋄ The number of additional velocity arrays
For additional velocity arrays the same holds, but now the information on the magnitude
of the additional velocities is most often generated by the processes library itself as e.g.
settling velocity of particles. Also in that case just state zero here, because the processes
library will itself automatically make the necessary additional velocity arrays and put the
settling velocities in the section of the third dimension, the vertical.
⋄ form of the input file structure
The first form of input is used here. The second form is documented in a following sec-
tion. It is rarely used because it is mainly convenient for the manual specification of the
hydrodynamics of relatively small models.
⋄ exchange pointers
The number of exchanges was specified earlier. Now for all of these exchanges it should
be specified between which cell numbers the exchange surface is located. That happens
with this part of the input.
⋄ dispersions
These are the constant dispersions that will act on all transported substances and will be
added to the dispersion array values. If additional dispersion arrays were specified, they
should be given values here. In the example this part can be absent.
⋄ velocities
If additional velocity arrays were specified, they should be given values here. In the exam-
ple this part can be absent.
⋄ areas
These are the exchange surface area magnitudes in m2 that are used to compute the
D·A
diffusive exchange flux in m3 /s with: flux = length .
⋄ flows
These are the flows across the exchange surfaces in m3 /s
⋄ lengths
34 of 95 Deltares
Hydrodynamic data
These are the exchanges lengths in the diffusive flux formula. They can be spatially
constant for a rectilinear grid, but it is most common that they are spatially variable. In all
cases it is most common that the file of values is generated by the hydrodynamic model
like in this example.
T
same model result as with the example at the start of the chapter would be obtained with e.g.:
Solvers 19 and 20 use a technique call ADI - Alternate Direction Implicit. They stem from the
regular grid Delft3D-FLOW environment and use almost identical source code. These solvers
require a matrix topology of grid cells. The dimension of this matrix is read from the input file
at this location. Also 3 integers are required, but they have different meaning:
⋄ the size of the fastest running (first) horizontal index of the matrix topology, called NMAX.
⋄ the size of the slowest running (second) horizontal index of the matrix topology, called
MMAX.
⋄ the size of the third index in the matrix topology, called KMAX.
Unlike the input for irregular solvers, you now must specify 1 for the 3rd direction if the model
is depth averaged, since then there is one layer of computational cells in the matrix. For a
size of zero the matrix would disappear.
like:
Deltares 35 of 95
D-Water Quality, User Manual
T
1 the number of the ’from’ segment
2 the number of the ’to’ segment
3 the number of the ’from-1’ segment
4 the number of the ’to+1’segment
AF The following properties can be identified:
⋄ the selection of the ’from’ and ’to’ segment numbers also defines the positive direction of
flow through the surface. Negative flow runs from ’to’ to ’from’.
⋄ for an open boundary cell / segment one specifies −n with n the sequence number of that
open boundary.
⋄ for closed boundaries and connecting inactive cells you may specify zero or you may
alternatively omit the specification (and then also state that you have a lower number of
exchanges in that direction of course).
⋄ the ’from-1’ and ’to+1’ entries are only used for some higher order scheme’s (5, 12 and
DR
14). If you do not use that solvers then you can just specify zero for these two entries.
⋄ D-Water Quality will just skip the entry in the computation if one of the ’from’ or ’to’ numbers
is zero or if both are zero and/or negative. Also the flow, area and lengths that are found
at that location in the files are neglected.
The table of 4 integers per exchange surface can be specified to D-Water Quality in several
forms. You start with an integer option number:
0 input comes from an external binary file
Optionally now UNFORMATTED and BIG_ENDIAN may be used as keywords to indicate
that the file structure deviates from the default of BINARY and LITTLE_ENDIAN. Then
the name of the file follows. This is generally the way to couple D-Water Quality with the
administration of a hydrodynamic model. The file contains:
⋄ For most solvers:
NOQ1 + NOQ2 + NOQ3 groups of 4 integers. The implementation for UNFORMATTED
files is such that each group of 4 integers forms a record.
⋄ For solvers on regular grids (e.g. 19 and 20):
Seven integers (in one record for UNFORMATTED files): NMAX, MMAX, NOSEGL,
⋄
KMAX, NOQ1, NOQ2, NOQ3. These seven integers are checked against earlier
input to identify that the file contents is compatible. NMAX, MMAX, KMAX should
correspond. NOSEGL is the highest active grid cell number that will appea in the
matrix and NOQ1, NOQ2, NOQ3 are the number of areas and flows that will be
contained in the corresponding hydrodynamic files.
The complete matrix of segment numbers (or zero for inactive grid cells) of one
⋄
layer. It has the size of NMAX*MMAX and is in one record for UNFORMATTED files.
1 input comes from this ASCII input file
36 of 95 Deltares
Hydrodynamic data
Optionally you may use the INCLUDE directive like everywhere in the D-Water Quality
input file. The input now contains:
⋄ For most solvers:
NOQ1 + NOQ2 + NOQ3 groups of 4 integers, like for Venice Lagoon at unstructured
grid:
1 2 0 0
1 3 0 0
2 3 0 0
.. .. .. ..
2228 2256 0 0
T
2228 2255 0 0
-9 2230 0 0
0 0 0 0
2230 -10 0 0
2231 2232 0 0
⋄ For solvers on regular grids (e.g. 19 and 20):
AF Four integers: NMAX, MMAX, NOSEGL, KMAX. These four integers are checked
⋄
against earlier input to identify that the file contents is compatible. NMAX, MMAX,
KMAX should correspond. NOSEGL is the highest active grid cell number that will
appear in the matrix.
The complete matrix of segment numbers (or zero for inactive grid cells) of one
⋄
4.5 Dispersions
DR
Deltares 37 of 95
D-Water Quality, User Manual
substances that are transported by water. The additional dispersion array has values zero in
the horizontal directions and has the vertical diffusion coefficient that was generated by the
hydrodynamic turbulence model. The constant horizontal and vertical diffusion values speci-
fied in this input file are added to the values that are generated by the processes library. So in
our sample case the horizontal diffusion coefficients will be 1.0 m2 /s and the vertical diffusion
coefficients will be 1.0E-07 + the value from the hydrodynamic model in m2 /s. There is an
input item for the process VertDisp called ScaleVdisp with default value 1.0 that allows
for scaling of the vertical diffusion as generated by the hydrodynamic model.
We are at the advent that hydrodynamic models may produce spatially varying horizontal
dispersion coefficients using HLES (Horizontal Large Eddy Simulation) models. This devel-
T
opment is induced by the use of increasingly smaller horizontal grid cells. The smaller the
horizontal grid cells are, the more important the local differences in horizontal mixing coeffi-
cients will be. Once models deliver such files for the horizontal direction with included vertical
coefficients in the vertical direction, the use of the ’-4’ and ’-2’ option of the preceding sec-
tion together with the declaration of an additional dispersion array, will do to incorporate such
AF
4.5.2.2
developments in D-Water Quality.
38 of 95 Deltares
Hydrodynamic data
water velocities. That is because it is a Finite Volume (FV) model. It solves the volumet-
rically integrated advection diffusion equations and uses flows rather than velocities for
that. However for a number of water quality processes it may be necessary to know the
water velocity. D-Water Quality computes this in the processes library by dividing the flow
by the area where the flow goes through. To get the velocities in the cell midpoints (or the
velocities that are representative for the cell as a whole) several averaging methods exist
in the processes library to average values at the cell interfaces. Increasingly more how-
ever hydrodynamic model using unstructured grids are used. Then the averaging process
is not so trivial any more. These models generally produce velocity files that are read by
input group 7 of the input processor.
T
3 Compute the thickness of cells
D-Water Quality compute the thickness of cells by dividing the volume of the cell by the
horizontal surface area of the cell. This gives a time varying thickness value that is used
in processes that e.g. compute the extinction of visible light in the vertical etc.
4 Compute superficial processes
AF D-Water Quality uses the horizontal surface area of cells to e.g. compute reaeration of
oxygen at the water surface or to compute the amount of settled sediments per m2 of the
bed.
The exchange areas for aim 1 and 2 are read in this section of the input file. The horizontal
areas are also contained in this dataset if the model is 3-dimensional. If however the model
is 2-dimensional depth averaged, then there are no horizontal exchange areas because there
are no vertical fluxes and transports. That is why horizontal areas for aim 3 and 4 are sepa-
rately stored in a variable called SURF. This variable is generally read as parameter or seg-
ment function in group 7 of the input file.
DR
The exchange areas are read through the standard input procedure for hydrodynamic data
that is described in the Annexes. Per exchange surface one value is read. One scale value
applies. As seen from the sample input file at the start of this chapter, this part of the input
is most commonly limited to ’-2’ and the name of the areas file that was generated by the
hydrodynamic model. Also input of ’-4’ and the name of a MULTIPLE_HYD file is regularly
used.
4.8 Velocities
If additional velocity arrays have been specified before, this is the place to specify there value,
or where they will come from. Additional velocities are incorporated in the solution of the
advection diffusion equation like the additional dispersions are. They act on the substances
where they have been specified for. If ’0’ was specified as additional velocity array number
for a substance then no additional velocity is applicable. Additional velocities generally play a
role as settling velocities and floating velocities of particulate substances heavier than water
or lighter than water. These velocities are generally computed by the processes library by
transport processesand automatically stored in arrays and applied for the substances where
they are ment for. So generally you then specify zero additional velocity arrays and this section
of the input file can be fully omitted.
Should you want to add additional velocity arrays yourself, then you follow exactly the same
Deltares 39 of 95
D-Water Quality, User Manual
input procedure as for areas and flows. The only difference is that if you specify 4 additional
velocity arrays, then you should apply the procedure for 4 values per exchange rather than for
one value per exchange as done for areas and flows. There is still 1 scale value per direction
NOQ1, NOQ2 or NOQ3 when present.
4.9 Lengths
The lengths between the midpoints of computational cells at both sides of interface areas are
used to:
T
1 Compute the diffusive mixing flux
The diffusive mixing flux is computed from the dispersion coefficient D, the surface area
A of the exchange surface between two cells, the distance between the cell midpoints
at both sides of the exchange are and the difference in concentrations at both sides by:
D·A
F lux = − length ∆C . The flux counteracts the gradient and is often seen as a diffusive
AF flow of: Df low = lengthD·A
in both directions, times the outgoing concentrations. A step
even further is to attach a physical meaning to the length term by calling it a mixing length
which is of course erroneous since it is just the distance between the midpoints of the two
∆C
adjacent cells and forms part of the concentration gradient: gradient = length .
2 Weigh concentrations in central schemes
If two adjacent cells differ strongly in size, one may distinguish the distance of the ’from’
cell midpoint to the interface area and of the ’to’ cell midpoint to the interface area. This
intuitive separation of two distances is also implemented in a number of higher order ’cen-
tral’ numerical schemes. This approach is increasingly more considered mathematically
questionable and is easily eliminated by the specification of two equal half values of the
DR
total distance between the cell midpoints rather than the two half values of the unequal
cell sizes. The latter have the same sum, but differ from each other.
Horizontal distances between cell midpoints are generally constant over time. This may pro-
duce a relatively small file with one specification that will hold for the whole simulation period.
In 3-dimensional models the water level change will change the vertical distances though. To
avoid huge files for this item, you can just specify vertical lengths of zero for this specification.
D-Water Quality will automatically fill in the correct vertical distances from the thickness of
cells as computed per time step by the cell volumes divided by the horizontal surface areas.
There are two options to specify lengths to D-Water Quality
0 Lengths are constant spatially and in time
This requires 1 scale value and 3 lengths values for the 3 dimensions. So in this case
no half lengths are specified and the third value is also required for depth averaged 2-
dimensionlan models. This option would only be appropriate for a sort of test cube of
identical small cubes as computational volumes.
1 Lengths vary spatially
This requires exactly the same input structure a for areas, flows and velocities with special
consideration that 2 values are needed per interface area, the ’from’-length and the ’to’-
length respectively. Per direction 1 scale values is required for ASCII input.
40 of 95 Deltares
Hydrodynamic data
areas
T
flow
lengthes
⋄ NOQ1 + NOQ2 + NOQ3 rows with:
’from’ cell number
⋄ ⋄ ⋄ ⋄ ⋄ ⋄ ⋄ ⋄ ⋄
Like in:
DR
4.11 Finalization
This part of the input file is finalized with the #4 end of fourth data group indicator.
Deltares 41 of 95
D-Water Quality, User Manual
T
AF
DR
42 of 95 Deltares
5 Open boundary conditions
This is the fifth group in the input file. This group may read like:
; Open boundaries
'River 1' 'River Williamsburg side ' 'River'
'River 2' 'River 100m from bank ' 'River'
.... .... ....
'River 12' 'River Brookmarsh side ' 'River'
'Ocean 1' 'Ocean at Cape Cod side ' 'Ocean'
T
.... .... ....
'Ocean 100' "Ocean at Mary's Lighthouse" 'Ocean'
ITEM 'River'
'Ocean'
CONCENTRATION USEFOR Continuity Cont
USEFOR Oxy O2
USEFOR PO4 Tot-P - Part-P MIN 0.0
USEFOR AAP Part-P
TIME LINEAR DATA Cont Tot-P Part-P NO3-N O2
2012/01/01-12:00:00 1.0 0.15 0.1 1.7 7.5 ; river
1.0 0.05 0.03 0.5 8.4 ; sea
DR
5.1 General
Open boundary conditions deal with the influence from outside of the model domain. To a
certain extent also waste loads do. Open boundary conditions however distinguish in some
important aspects from waste loads:
⋄ Open boundary conditions are contained in the transport schematization that comes from
the hydrodynamic model. They appear as negative integers in the ’from’-’to’ pointer table
for exchanges between the finite volumes. An entry of e.g. -6 refers to the 6th open
boundary condition. Waste loads do not have entries in the ’from’-’to’ pointer table.
⋄ Open boundary conditions come with a flow from the hydrodynamic model. Waste loads
may come with a flow from the hydrodynamic model, but may also be specified indepen-
dent of the flow model. The latter generally happens for waste flows that are so small that
they need not be contained in the hydrodynamic model. A city of 1 million inhabitants will
e.g. generate a waste flow of about 1 m3 /s but that amount may be too small to influence
hydrodynamic velocities in a tidal marine area.
⋄ By default the numerical scheme is expanded across the open boundaries by having dif-
fusion across open boundaries and/or having higher order flux correction terms across
open boundaries. If you want these effects be switched ’off’, you need to use the key-
words NODISP-AT-BOUND and/or LOWER-ORDER-AT-BOUND in the group 2 section
of the input file. If diffusion across open boundaries is used, e.g. for mimicking salt intru-
sion with a diffusion term for 1-Dimensional rivers entering a sea, the user must be aware
Deltares 43 of 95
D-Water Quality, User Manual
that the constant diffusion term of group 4 of the input file acts on all open boundaries. It
is then best to set the constant diffusion to zero and to give nonzero values where needed
to an additional diffusion array.
⋄ It is possible to specify a ’Thatcher-Harleman’ open boundary condition that will be dis-
cussed later in this section. For waste loads this option does not exist.
T
the model domain. The input processor reports the entry with the biggest sequence number
that it found. It also indicates all those entries within the range from 1 to the highest entry that
are not associated with an exchange surface with a model cell located within the model.
Because each exchange across the open boundary is an entry, the amount of entries can
become quite large in 3-Dimensional models. To assist somewhat with the specification of
AF open boundary conditions, there is the possibility to group the open boundaries with a ’type’
indicator.
For each open boundary entry, also those that are not associated with a model cell, the
following input is required:
⋄ A boundary-ID. The first 20 characters of the boundary-ID should be unique.
⋄ A boundary-name. This input is not used by D-Water Quality but assists the user in the
identification of the open boundary entry. The first 40 characters are echoed to the listing
file.
⋄ A boundary-type. The first 20 characters of the boundary type are recognized and can
be used to group the open boundary entries e.g. to the type ’Northern boundary’. For all
DR
It is possible to specify empty strings for all entries. If there are e.g. 112 open boundary
entries, one could specify here:
336*" "
The net effect of this specification will be that D-Water Quality fills in:
This is generally not so informative and also not so convenient. In the example at the start
of the chapter we distinguished a ’River’ boundary type and an ’Ocean’ boundary type. This
gives us opportunity to define a concentration at each of the two, without having to do so for
all the open boundary cells individually. Should we, for a certain substance, want to have
different values for the right bank and the left bank of the river and interpolate between them,
then this is still possible using the ’River 1’ to ’River 12’ ID values for that substance alone.
The names are not used by D-Water Quality but are helpful to identify which bank we are
meaning. Note that we used in the example at the start of the chapter double-quotes around
the last boundary name to enable the use of a single quote within the character string. The
identification of open boundaries given here is also used in the output files with mass balance
information to enhance the identification of the mass balance terms.
44 of 95 Deltares
Open boundary conditions
(
(Cout +Cbound ) (Cout −Cbound ) t−tout
+ · cos π if 0 < t < tout + lag
T
Cin = 2 2 lag
Cbound if t > tout + lag
For times since last outflow longer than the specified lag, the prescribed boundary concentra-
tion is applied. This means that the time lag feature is switched off by selecting 0 for the time
AF lag.
You specify these time lags as integers. If you earlier specified to use DDHHMMSS format for
times, then a time lag of 1 hour looks like 10000. If you did not specify that format, then you
should enter 3600.
You have the following three input options, they start with a ‘switch’ integer that is 0, 1 or 2:
0 No time lags.
1 Time lags for all entries like in the example at the start of the chapter.
2 Time lags with a default value and specified exceptions:
The exceptions consist of the entry number of the exception and the value to be used
DR
Deltares 45 of 95
D-Water Quality, User Manual
DATA in a block consist of a (series of) matrices. If you first specified the ITEM entries, then
the matrix consist of rows of concentration values. One for each item. If you first specified
CONCENTRATION entries, then the matrix consists of rows per substance and values for the
items on the rows. Be aware that D-Water Quality reads tokens only. D-Water Quality is not
aware of the layout that you use for the input file. You may put all your information on one line,
or you may put every item on a subsequent line. So you cannot leave a matrix entry blank
and you cannot assume that a new row starts with a new line. A new row starts if enough
data is read for the previous row. So if there is no value available, then you may specify -999.0
instead. This is interpreted by D-Water Quality as a missing entry.
Character strings may be embedded in single or double quotes. Quotes / double quotes are
T
only required if there are embedded blanks or embedded quotes in the string.
So either:
ITEM
'River outflow'
AF 'Northern boundary'
CONCENTRATION
Salinity
Continuity
Oxygen
DATA ; salinity continuity oxygen
16.0 1.0 7.5 ; river outflow
35.0 1.0 8.4 ; northern boundary
or:
DR
CONCENTRATION
Salinity
Continuity
Oxygen
ITEM
'River outflow'
'Northern boundary'
DATA ; river outflow northern boundary
16.0 35.0 ; salinity
1.0 1.0 ; continuity
7.5 8.4 ; oxygen
Note that ’River outflow’ may be a boundary ID of a single entry, whereas ’Northern boundary’
may be a boundary type consisting of many entries. Instead of a boundary ID, you may
also give an integer value say ’i’ as ITEM. D-Water Quality will then assume that you want
to specify the boundary with sequence number ’i’. Furthermore there may be more open
boundaries and substances in the model than those mentioned in this block. The others may
be defined in subsequent other blocks. The strings behind the semi-colons are comment
strings that are used here to make the table more readable.
ITEM
'River outflow'
'Northern boundary'
CONCENTRATION
USEFOR Salinity 'Sal o/oo'
46 of 95 Deltares
Open boundary conditions
Now the column headersare used as an identification of the column. They need not corre-
T
spond with the reserved names of the processes library, but they can be linked through the
USEFOR clause.
⋄ Note that the order of the columns is not important.
⋄ Note that the NO3-N column is not used.
⋄ Note that computations are possible:
AF The tokens and computational symbols should be separated by one or more blanks.
⋄ ⋄ ⋄
The computations act on whole columns, so if your columns are items, then the com-
putations may be less useful.
Up to now we have assigned one concentration value for each mentioned substance to each
mentioned boundary item. It is however common to have time varying open boundary condi-
tions consisting of a time series of concentrations. Time series start using the TIME keyword
before the DATA keyword. This tells the input processor that this input block consists of a time
series. Once you specified this keyword, D-Water Quality expects a series of matrices rather
than a single matrix. The most simple time series consist of 2 matrices for 2 time stamps.
Each matrix should be preceded by a ’time’ indication. That can be:
⋄ An integer in DDHHMMSS format if you specified to use that format in the group 1 input
section.
⋄ An integer in seconds if you did not specify to use the format.
⋄ If you gave a reference time in the model ID strings in the group 1 input section, then you
can also specify calendar dates here as e.g. 2012/02/28-12:35:00. The two ’/’, the
’-’ and the two ’:’ characters are required exactly in this form, otherwise the time string will
not be recognized.
D-Water Quality reads sets of a time and a matrix of data until it meets a reserved keyword
(mostly ITEM or CONCENTRATION) that starts the subsequent data block. Also the #5, the
end of block 5 signal, ends the processing of a time series.
Deltares 47 of 95
D-Water Quality, User Manual
T
5.4.5 Scale your input
If you copy and paste large amounts of data into your input file, then it is cumbersome if the
data does not have the units that are required for the simulation. If you have data in mole or in
µg/l rather than the g/m3 or mg/l that is required by D-Water Quality then it is convenient
AF that you just scale your input. You do so by specifying the SCALE keyword before the DATA
keyword. The SCALE keyword should be followed by as many scale factors as there are
columns in the matrices that you will provide. So you must provide 1.0 for each column that
will not be scaled. It is also possible to scale your input using the USEFOR clause and multiply
there by the appropriate scale factor.
is used instead of the DATA keyword and the data matrices that follow that keyword.
5.5 Finalization
This part of the input file is finalized with the #5 end of fifth data group indicator.
48 of 95 Deltares
6 Loads and withdrawals
This is the sixth group in the input file. This group may read like:
T
2642 'Ca. Deriva ' 'Casa Deriva ' 'Casa '
2706 'Fiume Vallio/Cle.d.V' 'Fiume Vallio/Cle de Veneto' 'Fiume '
CONCENTRATION FLOW
ITEM 1 2 3
DATA 0.84 0.9 2.6
AF ITEM 'Ca. Bianca/Altipiano'
'Scolo Scarpion
'Scolo Altipiano
CONCENTRATION
'
'
Continuity
Oxy
PO4
USEFOR AAP Tot-P - PO4 MIN 0.0
TIME LINEAR DATA
Continuity Tot-P PO4 Oxy
2005/01/01-00:00:00 1.0 0.4 0.25 7.5 ; load 1
1.0 0.6 0.31 6.5 ; load 2
1.0 0.37 0.16 8.3 ; load 3
DR
6.1 General
This is the sixth group in the input file. Waste loads are an external forcing to the system
in the form of added (or withdrawn) masses. They can be associated with point sources as
well as diffuse sources. There are similarities with open boundaries. Waste loads however
distinguish in some important aspects from open boundary conditions:
⋄ Loads and withdrawals do not play a role in the numerical solution of the substances
transport. They just add (or subtract) mass from computational cells. There functioning is
not contained in the ‘from’-‘to’ pointer table for exchanges between the finite volumes.
⋄ Loads and withdrawals are internally always expressed as mass/unit of time. Externally
they may be specified as a flow with a concentration, but alternatively also directly as
mass/unit of time. There need not be a flow associated with the waste loads.
⋄ If a load flow is substantial enough to be contained in the hydrodynamic model result,
then it depends on the coupling program with the hydrodynamic model whether that flow
becomes available for D-Water Quality input processing. For Deltares software, the sup-
ported flow modules write files with flow information from point sources or distributed
sources. These files can directly be used by D-Water Quality for its input processing
and only concentrations need to be attached.
⋄ If a load flow is contained in the hydrodynamic model, but if the hydrodynamic model does
not make an input file for D-Water Quality to obtain that flow, then you can instruct D-
Deltares 49 of 95
D-Water Quality, User Manual
Water Quality to compute the flow from the closure error in the hydrodynamics dataset
at that location. This requires that each computational cell has at most 1 waste load. If
there were more for one cell, then there is only one closure error and it is impossible for
D-Water Quality to determine which share of the error belongs to which load.
⋄ If a withdrawal has to withdraw water with the current model concentration, then this is
done through the specification of the withdrawal flow.
⋄ Specific options exist to support the treatment of distributed or diffuse sources.
⋄ Loads are specified for all substances, so also the non-transported, inactive substances.
Open boundary conditions are only accepted for transported, active substances
T
Note: The loads and withdrawals are applied explicitly for all solvers. This means that es-
pecially for withdrawals a maximum time step applies to avoid instabilities at the location of
the withdrawal. The maximum time step size should at least be less than the volume of the
segment of withdrawal divided by the withdrawn flow. In the near future it may be expected
AF that for implicit solvers also the process of withdrawing water will be implemented in an implicit
way in order to eliminate this stability constraint.
identification of the load entry also in mass balances. The first 40 characters are echoed
to the listing file.
⋄ A load-type. The first 20 characters of the load type are recognized and can be used to
group the load entries e.g. to the type ’Agriculture’. For all entries of a type, one identical
concentration can be specified.
It is possible to specify empty strings for all entries. The net effect of this specification will be
that D-Water Quality fills in strings for the entries itself. This is generally not so informative
and also not so convenient.
50 of 95 Deltares
Loads and withdrawals
These keywords come instead of a cell number, and must always be followed by either MASS
or CONC (see Load entry options in 6.2.2). The consequence is that all cells that have a
surface, have a bank or have a bed are affected by this waste load specification. The ID,
name and type string are still required to identify the load in the further specification blocks.
T
You may optionally precede the waste-load-ID with one of 4 keywords:
⋄ MASS
This indicates that the information that follows for this load is to be considered as mass/unit
of time (generally g/s). Any also specified FLOW value will not be used.
⋄ CONC
AF This indicates that the information that follows for this load is to be considered as concen-
tration (generally g/m3 ). Flow information is now required to obtain waste loads other
than zero for this option.
⋄ RAIN
This indicates that the specified concentrations should be used by D-Water Quality if the
flow is positive and that zero concentrations should be used if the flow is negative (like for
evaporation).
⋄ WELL
This indicates that the specified concentration should be used if the flow is positive and
that the model concentration should be used if the flow is negative (like for groundwater
abstraction).
DR
If the keywords are missing, then the default waste load processing of D-Water Quality applies.
This default load processing consists of:
⋄ No flow is specified or the specified flow is exactly zero:
Then all values for the substances are considered to be expressed in mass/unit of time
(generally g/s).
⋄ The specified flow is positive:
Then the values for the substances are used as concentrations and mass is determined
by multiplying them with this flow rate.
⋄ The specified flow is negative:
If concentrations are not zero, the specified concentrations are withdrawn.
⋄ ⋄
This default behavior is tricky for a number of reasons. If e.g. a specified time series for the
flow contains zero values then suddenly, within the time series, the specified concentration
would be interpreted as a mass. The same type of sudden shift in behavior would appear
with withdrawals when the concentration becomes zero within a time series. Finally if flow
and / or concentration values are specified as time series and are linearly interpolated, then
it becomes increasingly difficult to identify when the value becomes zero and what the actual
load will be. Sometimes a small non-zero flow value of e.g. 1.0E-20 is included to force the
values to remain concentrations rather than mass. To avoid this ambiguity, the keywords are
introduced to give the user full control. Please note that the keywords apply per waste load,
so not for all together, but also not per substance or per input block.
Deltares 51 of 95
D-Water Quality, User Manual
T
a number of substances.
dataset then the closure error computation will automatically produce a zero value.
ITEM
'Amsterdam wwtp'
'Rotterdam harbor'
CONCENTRATION
FLOW
Ecoli
Oxygen
DATA ; flow m3/s EColi oxygen
52 of 95 Deltares
Loads and withdrawals
or:
CONCENTRATION
FLOW
Ecoli
Oxygen
ITEM
T
'Amsterdam wwtp'
'Rotterdam harbor'
DATA ; ‘Amsterdam wwtp‘ ‘Rotterdam harbor‘
1.2 3.1 ; FLOW
1.0E+08 0.5E+06 ; Ecoli
7.5 8.4 ; Oxygen
AF
6.3.3 Column headers and computations
Within one or more input blocks you may apply column headers that are no comments in the
following way:
ITEM
Agriculture
Woods
CONCENTRATION
USEFOR Continuity Cont
DR
USEFOR Oxy O2
USEFOR PO4 Tot-P - Part-P MIN 0.0
USEFOR AAP Part-P
DATA
Cont Tot-P Part-P NO3-N O2
1.0 0.15 0.1 1.7 7.5 ; Agriculture
1.0 0.05 0.03 0.5 8.4 ; Woods
Now the column headers are used as an identification of the column. They need not corre-
spond with the reserved names of the processes library, but they can be linked through the
USEFOR clause.
⋄ Note that the order of the columns is not important.
⋄ Note that the NO3-N column is not used.
⋄ Note that computations are possible:
The tokens and computational symbols should be separated by one or more blanks
⋄ ⋄ ⋄
The computations act on whole columns, so if your columns are items, then the com-
putations may be less useful
Deltares 53 of 95
D-Water Quality, User Manual
time series consists of 2 matrices for 2 time stamps. Each matrix should be preceded by a
’time’. This can be:
⋄ An integer in DDHHMMSS format if you specified to use that format in the group 1 input
section.
⋄ An integer in seconds if you did not specify to use the format.
⋄ If you gave a reference time in the model ID strings in the group 1 input section, then you
can also specify calendar dates here as e.g. 2012/02/28-12:35:00. The two ’/’, the
’-’ and the two ’:’ characters are required exactly in this form, otherwise the time string will
not be recognized.
T
D-Water Quality reads sets of a time and a matrix of data untill it meets a reserved keyword
(mostly ITEM or CONCENTRATION) that starts the subsequent data block. Also the #6 end
of data group 6 signal ends the processing of a time series.
AF
6.3.5 Linear interpolation
The default processing of time series is that the specified value at a specified time in used
up to the next specified time. Then the value switches to the next specified value, a so-called
block wave. For one or more of the input blocks you may alternatively want to interpolate lin-
early in between two specified values at specified times. To make D-Water Quality interpolate
your time series linearly, you insert LINEAR after the TIME keyword and before the DATA
keyword. Also the BLOCK keyword is supported, but it is superfluous since this is the default
processing of time series.
If you copy and paste large amounts of data into your input file, then it is cumbersome if the
data does not have the units that are required for the simulation. If you have data in mole or in
µg/l rather than the g/m3 or mg/l that is required by D-Water Quality then it is convenient
that you just scale your input. You do so by specifying the SCALE keyword before the DATA
keyword. The SCALE keyword should be followed by as many scale factors as there are
columns in the matrices that you will provide. So you must provide 1.0 for each column that
will not be scaled. A scale factor can be especially useful for loads through rainfall if you have
rain data in mm/day whereas you have to provide your input in m/s. Also concentration data
for coliforms (MPN/100 ml) generally need to be converted. Alternatively the USEFOR with
multiplication can be used to scale the input.
54 of 95 Deltares
Loads and withdrawals
T
and the concentrations in another block, each with there own number of time values, then
D-Water Quality will evaluate the flow and concentration independently per time step and
then multiply them at run time to obtain the load.
⋄ Group waste load concentrations for a specific class of loads
With the above procedure it is easy to provide e.g. the waste load concentrations for many
AF loads of a certain class like ’agriculture’ in one block. With the directive
INCLUDE “..\data\agriculture.dat”
you can retrieve that information from a separate file.
⋄ Separate time varying concentration data and constant concentration data
You just place them in different blocks.
⋄ If you say ITEM then D-Water Quality expects strings with items. It signals if such a string
is neither an item (a load or a load type) nor a new keyword.
⋄ If you say CONCENTRATION then any pending procedure for item processing stops and
the procedure for substances starts. It signals if your substance entries are not recognized
as model substances and the entry is also not a new keyword. USEFOR is allowed, but
should be followed by a character token that is found as column header and optional
computational instructions. If a computational operator (+, -, *, /, MIN, MAX) is followed by
a character token, then the new character token should either be a new column header or
a recognized keyword.
⋄ If you say DATA then data should follow. If you however specified TIME before, then
first a ’time’ stamp should be provided. That can be an integer or a calendar time string.
If the first time stamp is a character token that is not an absolute time string, then D-
Water Quality assumes that you started to provide column headers.
⋄ If you specified a matrix of input data, then either an integer time or a calendar time string
should follow, followed by the next matrix or a new keyword should follow to end the input
block and start a new input block.
6.4 Finalization
This part of the input file is finalized with the #6 end of sixth data group indicator.
Deltares 55 of 95
D-Water Quality, User Manual
T
AF
DR
56 of 95 Deltares
7 Process steering
This is the seventh group in the input file. This input group may read like:
T
; dddhhmmss
000000000 3.44E+00 ; Begin year
182120000 2.10E+00 ; Half way
365000000 4.44E+00 ; End year
7.1 General
The water quality processes make the model to a water quality model. They are ’objects’ in
the sense of the ’Component Software’ philosophy. It is important for the user to know that
there are 2 modes for the processes:
DR
1 They are switched on automatically by D-Water Quality with internal inference rules.
2 They are switched on by the user.
Because of unwanted side effects, method 1 is hardly used any more and this manual will
assume the use of method 2.
The user generally starts the PLCT (Process Library Configuration Tool). That is part of the
Graphical User Interface. This is a multi-level user interface to select substances, processes
and process steering that will be provided by the user rather than using the defaults for the
process. The PLCT also enables the selection of candidate extra output variables. These are
generally intermediate computations (like total biomass, total suspended solids etc. from the
fractions). They can also be meaningful derived variables like Chlorophyll, whereas the pro-
cesses library models algae as Carbon and Secchi depth whereas the model uses extinction
coefficients.
The result of the PLCT selection process is a readable ’*.sub’ file. This file is ingested by the
user interface. In the user interface the user attaches his process steering to the items that
were selected with the PLCT. In the user interface the user also selects which of the candidate
output variables he really wants to include in what output files. The user interface generates
a D-Water Quality input file. This documentation describes the process steering part of the
D-Water Quality input file with the aim to allow the user to modify this section of the input file,
using options that are not available through the user interface. It is generally very useful to
have an existing input file or a user interface produced input file as starting point. It is very
tedious to construct this part of the input file without using the PLCT, because the *.sub file
as produced by the PLCT will list the processes IDs, the substance IDs and the IDs of the
selected input and output variables by their reserved character string. The only alternative is
to select them manually by running through the technical reference manual of the processes
library and copying the IDs that are mentioned there into the input file. It is advised to only
use the manual for details on specific processes rather than to construct this section of the
input file fully from the manual.
Deltares 57 of 95
D-Water Quality, User Manual
T
ent per grid cell. The elevation of the bed below reference level could be an example.
⋄ FUNCTIONS
These are items that have the same value for all grid cells, but that may vary during the
course of the simulation. The annual pattern of solar radiatiation on the model may be an
example of this type of input.
AF ⋄ SEG_FUNCTIONS
These are items that vary in time and that may have different values per grid cell. They
are called ”segment function“ in D-Water Quality terminology. This is huge information
for a detail 3D model with many time steps. This information is generally produced by
other software and attached as a file to this simulation. The temperature, salinity and
suspended sediment concentration as computed by the hydrodynamic model are of this
type, but also the vertical diffusion coefficient from the hydrodynamic model, that will be
used in the D-Water Quality simulation is of this category.
It is important to realize that any steering item for process behavior can be any of these four
DR
types. For one simulation the temperature can be fixed both in time and all over the place. It
will then be among the CONSTANTS. For another simulation it can be prescribed as an annual
time function that is the same for each grid cell. It will then be among the FUNCTIONS in the
input. For yet another simulation a spatial field of temperature values can be used and you
will see it in the PARAMETERS input part. The temperature steering can also vary per time
step and per grid cell and be among the SEG_FUNCTIONS. An example for the latter is e.g.
the temperature file that is computed by a 3D hydrodynamic stratification model. Which type
of input is used for a certain simulation is up to the user, the processes library automatically
deals with any selection the user makes.
A steering item can also be part of the D-Water Quality simulation, the water depth of a
grid cell is an example, but also the temperature can be computed by D-Water Quality itself
rather than being provided as external steering. If this is the case the user does not need
to do anything, D-Water Quality automatically attaches the model information to the process.
For temperature this means that de D-Water Quality modeled temperature is used unless
temperature is specifically provided as external steering by the user. In the latter case, the
user specification of the external steering overrules the presence as state variable.
58 of 95 Deltares
Process steering
T
steering coefficients from different sources of information, like meteorology or a certain mea-
sured dataset. In the following the 4 types of data blocks will be documented further.
7.3.1 CONSTANTS
AF To enter constants, you write CONSTANTS in the file. Then you write the IDs of the items that
you want to provide as constants. The IDs must correspond exactly with the reserved names
of the processes library, but they are not case sensitive. In the most simple case a collection
of IDs is followed by the keyword DATA and then the values of the constants follow. You will
find for example input like:
CONSTANTS
SWresusalg
SWAdsP
KdPO4AAP
MaxPO4AAP
RcAdPO4AAP
DR
pH
DATA
1.00000e+000 ; SWresusalg
0.00000e+000 ; SWAdsP
1.00000e+000 ; KdPO4AAP
5.00000e-003 ; MaxPO4AAP
5.00000e-001 ; RcAdPO4AAP
8.20000e+000 ; pH
But since you can insert an arbitrary number of data blocks, you could equally well use:
If the specified constants are resolved, the D-Water Quality input processor requires either a
keyword that starts the next data block or the #7 to end this group of input.
Deltares 59 of 95
D-Water Quality, User Manual
using only those processes that are explicitly switched on. Otherwise D-Water Quality tries
to figure out itself which processes it will switch on. This automatic procedure has however
a number of unwanted side effects so it is hardly used any more. Processes are switched
to ’on’ furthermore by the presence of a constant ACTIVE_proc_name. It does not
matter what value is attached to the constant. The presence of the constant alone will
switch the process ’on’. The constants in the sample input on constants are important
for processes associated with adsorbed and soluble phosphorus (AAP and PO4). So you
should not be surprised to see in the list of constants also entries like:
CONSTANTS ONLY_ACTIVE DATA 1.0
CONSTANTS ACTIVE_AdsPO4AAP DATA 1.0
T
CONSTANTS ACTIVE_Sed_AAP DATA 1.0
CONSTANTS ACTIVE_Res_AAP DATA 1.0
In most applications you will see that a data value of 1.0 is used, but the exact value does
not matter. So also with the value of 0.0 the processes are switched to ’on’. It may be
good practice for the readability of the input file, to use 1.0 for the ’on’ switching. If you
AF
want to swicth a process ’off’ temporary but leave the entry in the input file, then you just
insert a comment character at the beginning of that line.
⋄ closure error switch
If the hydrodynamic files are exhausted and the simulation continues, then D-Water Qual-
ity automatically rewinds the hydrodynamic files. Because the model volume at the end
of the dataset may not equal to the model volume at the start, an inconsistency arises.
The default approach to this inconsistency is that D-Water Quality preserves mass. This
means that you see that the time series of concentration values make a ’hiccup’ because
of the discontinuous volume. If the CLOSE_ERR constant is present however, the time
series of concentration values will remain smooth and D-Water Quality adapts the mass
to cause a smooth concentration curve behavior. The amount of volume that has to be
DR
added or removed at the rewind of the hydrodynamic datasets in this case is displayed in
the monitoring file. This feature may give rise to severe errors if a grid cell was temporary
dry at the start and wet at the end of the hydrodynamic database or the reverse.
⋄ constants associated with implicit solvers
A number of constants are associated with implicit solvers. Here they are listed together
with their default values.
CONSTANTS swprecond DATA 3.0 ; preconditioner
CONSTANTS maxiter DATA 100.0 ; max nr iterations
CONSTANTS tolerance DATA 1.0D-7 ; tolerance
CONSTANTS swscale DATA 1.0 ; row scaling
CONSTANTS novec DATA 50.0 ; Krilov space size
CONSTANTS "iteration report" DATA 1.0 ; iteration report
The default for preconditioner is "lower and upper" tridiagonal, other values are 0 for "none"
and 1 or 2 for "lower" or "upper" alone. The default for row scaling is ’on’. Use 0.0 to switch
it ’off’. The Krilov space size may prevent the model to fit in 2GB of memory. The value
may then be reduced to 25. It is not advisable to reduce it further. The default for the
iteration report is ’on’ and output is written to the monitoring file, but in many input you will
find this constant with the value 0.0 and then it is switched ’off’ to avoid bulky output.
⋄ Parallel computing
D-Water Quality supports parallel computing on multi core PC’s. This feature is generally
switched ’off’. If you are confident with your model, you may switch it ’on’ by giving:
CONSTANTS nothreads DATA 0.0 ; OMP-parallelism 'on'
With a value of 0.0 D-Water Quality will itself determine how many threads can be used.
With a positive value you determine the number of threads. The default is -1.0 which
means ’off’. Implicit solvers need a Krilov space for each thread. This can become large
for e.g. 6 core PC’s with hyper-threading featuring 12 threads. Then you better use a
smaller positive number for the number of threads than the allowed number of 12 that you
will get with a value of zero.
60 of 95 Deltares
Process steering
T
process, unpredictable results may occur for incomplete water columns.
⋄ Z-layer model initial conditions
It is difficult, especially for bigger models, to manually specify initial conditions for bed
variables in Z-layer models, because you generally do not know at what level the first wet
cell appears. The solution is to specify initial conditions for bed variables (non-transported
AF
substances) in the lowest layer irrespective of whether it is below the bed or not. Further-
more you specify the constant Z_Thresh with a value of e.g. 0.001. Then all cells with
a waterlayer thickness of 1 mm or below will be considered located below the bed. Those
cells are set inactive, the initial condition is set to zero and the specified value is migrated
upward until the first wet cell of the water column is reached.
⋄ Drying and flooding
The way a hydrodynamic model administrates its drying and flooding is sometimes not fully
clear to D-Water Quality. To ensure some basic safety, D-Water Quality has itself also a
drying and flooding detection mechanisms to ensure that the volume of its computational
cells will not fall to zero or even below zero. D-Water Quality will use a default threshold
DR
of 0.001 m or 1 mm. Below this water level a cell is considered to have ran dry. You can
change this default value by specification of a constant with the name DRY_THRESH and
giving it a value other than 0.001. The value is multiplied with the value of the horizontal
surface area of the horizontal computational cells to obtain the threshold per water collumn
locally in m3 . If no constant or segment function with the name SURF is found, then D-
Water Quality cannot determine the threshold volume in m3 by multiplication with SURF.
For that situation the value of the constant DRY_THRESH is directly interpreted as a value
in m3 and the default value if no constant DRY_THRESH is found amounts to 1.0 m3 .
Please note that the procedure is used for the whole water column, so not for the cell at
one layer. This reflects the fact that either the water column ran dry locally or it is wet.
Except for Z-models (see the item above), individual cells in a 3D model cannot run dry,
the column does.
⋄ Time step multiplier for the BLOOM process
The algae competition module BLOOM is generally operated on longer time spans than
the remainder of the water quality processes. For many water quality processes a time
step size of half an hour would do. A common time step size for the BLOOM process is a
day. This requires:
CONSTANTS TimMultBL DATA 48.0 ! factor from 0.5 hour to a day
You should be aware that when you need this constant that you have to adapt the constant
as soon as you are changing the integration time step size for the other processes.
Deltares 61 of 95
D-Water Quality, User Manual
7.3.2 PARAMETERS
The keyword PARAMETERS is followed by a list of one or more parameter IDs. The IDs
must correspond exactly with the reserved names of the processes library, but they are not
case sensitive. If later on column headers are used and/or the parameter values are modified
by computational instructions, then the USEFOR construct as described for boundaries and
waste loads also applies here. This list ends if a reserved keyword is met. Valid reserved
keywords are:
⋄ DEFAULTS, ALL, SEGMENTS, INPUTGRID
These keywords are associated with definition of the way the data will be attached to the
T
computational cells, the segments.
DEFAULTS
⋄
With this keyword it is expected that for each parameter one value will follow. This
value will be used for all segments.
AF ALL
⋄
With this keyword it is expected that for each parameter and each segment a value will
be given.
SEGMENTS
⋄
With this keyword it is expected that a list of segment numbers will follow for which the
parameter values will be specified.
INPUTGRID
⋄
With this keyword it is expected that the name of an earlier defined grid is mentioned.
The parameter values will be given for the cells of this grid and will then be expanded
to other grids when needed by D-Water Quality.
⋄ BINARY_FILE or UNFORMATTED
DR
This keyword indicates that the mentioned parameters will be retrieved from a binary file
or an unformatted file (which is a binary file with special FORTRAN compiler depending
structure of records). This keyword should be followed by the file name. The parameters
are expected to be located in the file in the order of their appearance in the list that was
just closed by the keyword. First all parameters for computational cell 1 are expected, then
all for cell 2 etc.
⋄ BIG_ENDIAN
This keyword indicates that the binary file or unformatted file has its data in BIG_ENDIAN
structure. This structure is common for files on mainframe computers and on some mas-
sive parallel computers. BIG_ENDIAN files are also produced by the TELEMAC hydro-
dynamic models.
⋄ ODS_FILE
This is a sort of self descriptive proprietary Deltares file format that is not further docu-
mented here. This keyword should be followed by the file name of the file.
⋄ DATA
This keyword starts data entry. It will produce an error if not first the segments are defined
where the parameters will be given for. So first one of the keywords ALL, DEFAULTS,
SEGMENTS, INPUTGRID is expected with associated additional information if that is
needed for the keyword.
For DEFAULTS, as many values are expected as there are parameters in this block.
⋄ ⋄
For SEGMENTS, all parameters of this block are expected for all segments that were
mentioned by number after the SEGMENTS keyword.
For INPUTGRID, all parameters of this block are expected for all segments of the
⋄
This is the biggest file and is often produced by the hydrodynamic model or by the user
interface, but you could of course yourself also specify 2345*3.1 9380*2.8 2345*2.4
62 of 95 Deltares
Process steering
Like with boundary conditions and loads, the data may be preceded by column headers dis-
playing the names of the columns in the input file. If information comes from a binary or
unformatted file, then the parameters are expected in the order in which they are mentioned
in this block. First all parameters for segment 1, then all parameters for segment 2 etc.
T
PARAMETERS
Surf
Bottomdept
ALL
BINARY_FILE BIG_ENDIAN '..\data\Bodensee.par'
AF but also of:
PARAMETERS 'SURF'
INPUTGRID 'water-grid' BINARY_FILE 'surf.par'
PARAMETERS 'SURF'
INPUTGRID 'sediment-grid' DATA INCLUDE 'surf-sediment.dat'
Note that by the last 2 specifications the water-grid gets its horizontal surfaces from a file
coming through the user interface from the hydrodynamic model and that additionally the
horizontal surfaces of the much coarser sediment-grid with the layered water bed come from
a readable ASCII file that is included here.
7.3.3 FUNCTIONS
The keyword FUNCTIONS is followed by a list of one or more function IDs. The IDs must
correspond exactly with the reserved names of the processes library, but they are not case
sensitive. If later column headers are used and/or the function values are modified by compu-
tational instructions, then the USEFOR construct as described for boundaries and loads also
applies here. This list ends if a reserved keyword is met. Valid reserved keywords are:
⋄ LINEAR, BLOCK
These keywords indicate the interpolation mechanism to be used for the functions be-
tween the specified points. BLOCK is the default procedure, so that keyword is superflu-
ous.
⋄ HARMONICS
This keyword indicates that harmonic functions will be specified. These functions are not
interpolated, but analytically evaluated according to:
n
X t
ft = faverage + amplitudei · sin − phasei · 2π
i=1
periodi
Deltares 63 of 95
D-Water Quality, User Manual
⋄ FOURIERS
This keyword indicates that Fourier functions will be used. These functions are not in-
terpolated, but analytically evaluated. The analytical formula is the same as for har-
monics with the distinction that there is a base period for the first component and that
periodi = baseperiod/i with i the component number.
⋄ TIME_DELAY
This keyword indicates that the times of the functions specified should be delayed with a
certain amount of time. It is followed by the time delay value that is an integer in units of
the system clock (generally seconds) or an integer in DDDHHMMSS or YYDDDHH format
if that format was previously selected for input of times. The time delay value allows the
T
use of unaltered datasets from other years or months for the model years or months. The
alternative would be to edit the time strings in those files to make them fit for the different
year. It should be anticipated that a day could be lost or should be interpolated at the end
of some February months.
⋄ BINARY_FILE, UNFORMATTED, ODS_FILE
AF
These keywords are not common for functions and they are even not allowed if the use of
HARMONICS or FOURIERS is specified.
⋄ DATA
This keyword starts data entry. Expected is:
optional column header strings for the columns that will follow. De input processor will
⋄
then select the appropriate columns and will skip the non used columns.
for normal time series specified at breakpoints, the input processor expects a se-
⋄
quence of:
◦ a time integer or an absolute calendar time string
◦ the function values at that time in the order of the list of this block or according to
DR
◦ the faverage values for the functions in the order of the list of this block.
◦ as many sets of input as there are harmonic components with:
▷ a time interval integer for this harmonic component in units of the system clock
giving the periodi of harmonic component i.
▷ a real value between 0 and 1 or between -0.5 and +0.5 for phasei of this
harmonic component with respect to the start of simulation
▷ the amplitudei values of this harmonic component for the functions in the
order of the list of the block
for FOURIERS functions, the input processor expects a sequence of:
⋄
◦ a time interval integer in units of the system clock giving the baseperiod of this
Fourier series.
◦ the faverage values for the functions in the order of the list of this block.
◦ as many sets of input as there are Fourier components with:
▷ a real value between 0 and 1 or between -0.5 and + 0.5 for phasei of this
Fourier component with respect to start of simulation
▷ the amplitudei values of this Fourier component for the functions in the order
of the list of the block
Data entry ends when either a keyword is met that opens a new input block or when the
#7 is met to end this group of input.
64 of 95 Deltares
Process steering
7.3.4 SEG_FUNCTIONS
The keyword SEG_FUNCTIONS is followed by a list of one or more segment-function IDs.
The IDs must correspond exactly with the reserved names of the processes library, but they
are not case sensitive. This list ends if a reserved keyword is met. Valid reserved keywords
are:
⋄ LINEAR, BLOCK
These keywords indicate the interpolation mechanism to be used for the segment-functions
between the specified points. BLOCK is the default procedure, so that keyword is super-
fluous.
T
⋄ TIME_DELAY
This keyword indicates that the times of the functions specified should be delayed with a
certain amount of time. It is followed by the time delay value that is an integer in units of
the system clock (generally seconds) or an integer in DDDHHMMSS or YYDDDHH format
if that format was previously selected for input of times. The time delay value allows the
AF use of unaltered datasets from other years or months for the model years or months. The
alternative would be to edit the time strings in those files to make them fit for the different
year. It should be anticipated that a day could be lost or should be interpolated at the end
of some February months.
⋄ BINARY_FILE, UNFORMATTED, ODS_FILE
These keywords are very common for segment-functions because these are generally
generated by other models. These keywords are generally followed directly by the file
name of the file, but it is also possible to specify BIG_ENDIAN to indicate that the file is
written with that file structure.
⋄ MULTIPLEHYD_FILE followed by the file name of such a file. See the annex of this
manual for the description of multiple hydfiles.
DR
⋄ DATA
ASCII input of segment-function time series specified at breakpoints is rare, because this
information is generally voluminous. Should it nevertheless occur then the input processor
expects a sequence of:
a time integer or an absolute calendar time string
⋄ ⋄
the function values at that time in the order of the list of this input block. Unlike e.g.
parameters, this data is required as: for all computational segments the values of
segment function 1; for all computational segments the values of segment function 2;
.... etc.
Data entry ends when either a keyword is met that opens a new input block or when the
#7 is met to end this group of input.
7.4 Finalization
This part of the input file is finalized with the #7 end of 7th data group indicator.
Deltares 65 of 95
D-Water Quality, User Manual
T
AF
DR
66 of 95 Deltares
8 Initial conditions
This is the eighth group in the input file. This input group may read like:
This is old-style input to start from a restart file. It could also be:
T
MASS/M2 ; The bed substances are specified in mass/m2
2 ; Input with defaults
23*1.0 ; Scale values
; Continuity Salinity im1 im2 oxy nh4 etc.
AF 1.00
2
1.00
24.00 5.00 0.00
; number of overridings
13816 ; first overriding
0.00 15.0 0.00
6.50
8.00
0.15
1.20
...
...
23456 ; second overriding
1.00 0.00 5.0 0.00 9.00 0.40 ...
This is old-style input to start from a set of prescribed initial values with exceptions for 2 cells.
It could also be new style input especially suitable for models with a layered water-bed:
INITIALS
Continuity Bulkvolume Salinity im1 im2 oxy nh4 etc.
INPUTGRID
sediment-zone ; this grid was defined in input group 3
DATA
1.00 1.00 24.00 3.44E05 2.29E05 0.05 0.01 ... ; layer 1
1.00 1.00 24.00 3.66E05 2.44E05 0.05 0.01 ... ; layer 2
1.00 1.00 24.00 3.86E05 2.57E05 0.05 0.01 ... ; layer 3
#8 ; delimiter for the eighth group of input data
8.1 General
Initial conditions should be given for all modeled substances and all computational volumes
(segments). The initial conditions are given as a concentration value for all active substances
that are transported with the water. D-Water Quality itself uses masses of the substances
as state variables and the concentrations of the state variables are derived entities for out-
put processing and for the evaluation of water quality process kinetics. This means that D-
Water Quality will multiply the initial concentration values with the volumes of the segments to
initialize its state variables for simulation. D-Water Quality also contains inactive substances
that are not transported with the water because they are located on the water bed or because
they are part of the layered water bed. In the past the latter type of substances had to be ini-
tialized directly by their mass per computational volume. That was very cumbersome because
computational volumes could differ and are largely unknown to the user. The user is just using
the output of a hydrodynamic model for volumes, areas and flows. Not so long ago this issue
was resolved by using the unit mass/m2 as ’concentration’ unit for these non-transported
substances.
Deltares 67 of 95
D-Water Quality, User Manual
A second major change in the processing of initial conditions was a consequence of the
layered bed model. Now the user can define a layered bed underneath the water phase. But
since the geometry of the water phase is generally determined by the hydrodynamic model
that produces the water flows and turbulences, additional geometry needs to be defined for
the bed. That is done in group 3 of the input file by the definition of a grid within the bed that
is linked with the overlying water grid. In this group 8 of the input file we will see how variables
within that grid in the water bed are initialized.
T
This specification is not convenient for the layered bed model, but may still be convenient for
simpler models.
This is an older type of initial condition file that is no longer produced, but may
still be available as remnant from older runs. The file just contains a matrix of
DR
real numbers. D-Water Quality assumes that any passive substances in this file
are given as mass/gridcell because that was common when the file was written
(most likely by the user interface.
A so-called .res file
⋄
This file is still produced as restart file by D-Water Quality | itself. It will be phased
out soon and it is advised to not use this file any more. Produced by the newer D-
Water Quality releases this file will contain the passive substances as mass/m2 .
Produced by the older releases it contains the passive substances as mass/gridcell
and is identical to the .ini file.
The runID_res.map file
⋄
This file is now produced. It contains information that allows you to check its con-
tent with any graphical postprocessor of D-Water Quality results, because it is a
standard D-Water Quality simulation result file with only one time step included: the
result at ’end-of-simulation’. This file is presently also produced by the user inter-
face and it contains information that allows D-Water Quality also to identify whether
the passive substances are initialized as mass/m2 or as mass/gridcell. Any
necessary conversion is performed automatically.
1 for the ASCII input file
This ASCII input file will contain:
The TRANSPOSE directive (optional)
⋄
This directive allows the specification of the matrix of initial conditions in inter-
changed row - column order.
An integer switch (required)
⋄
68 of 95 Deltares
Initial conditions
Then for all substances in the order that was mentioned in group 1 values
should be given for all segments. First all values for segment 1, then all values
for segment 2, ... and so on. For small models with not too many substances,
this is still possible by e.g.:
T
But for larger models with numerous grid cells, you may want to say:
TRANSPOSE
1 ; Input without defaults
1.0 ; Scale value
AF 23764*1.00
23764*24.0
23764*5.00
;
;
;
Continuity
Salinity
im1
23764*0.00 ; im2
23764*6.50 ; Oxy
23764*0.15 ; NH4
You can specify only one scale factor for all substances with the TRANSPOSE
keyword
INITIALS
Continuity Salinity im1 im2 oxy nh4 etc.
INPUTGRID
water-zone ; this grid was defined in input group 3
DATA
1.00 24.00 5.00 0.00 6.50 0.15 ...
INITIALS
Continuity Bulkvolume Salinity im1 im2 oxy nh4 etc.
INPUTGRID
sediment-zone ; this grid was defined in input group 3
DATA
; layer 1
Deltares 69 of 95
D-Water Quality, User Manual
Here 2 input blocks are given, one acting for the 1 cell ’water-zone’ and a second one acting for
the 3 cell ’sediment-zone’ that were defined in group 3 of the input file. These initial conditions
are expanded automatically by D-Water Quality to all the grid cells that are contained in the
mentioned zones. This example illustrates why this way is more convenient especially for the
T
layered bed approach .
Both ways are likely to be continued in future releases, because once a simulation is made
using a layered bed model, it remains convenient to initialize the next simulation simply with:
AF 0
lpr001_res.map
#8
; initials from binary restart file
; name of the restart file
; delimiter for the eighth group of input
INITIALS
Salinity
DR
NO3
USEFOR Diat01 Diatoms * 0.25
USEFOR Diat02 Diatoms * 0.25
USEFOR Diat03 Diatoms * 0.50
DATA Salinity NO3 Diatoms
16.0 1.0 0.5
8.5 Finalization
This part of the input file is finalized with the #8 end of eighth data group indicator.
70 of 95 Deltares
9 Model output
This is the ninth group in the input file. Input in this group may read like:
T
'Chlfa' 'volume'
'SS' 'volume'
'DisCu' 'volume'
'TotN' 'volume'
'DIN' 'volume'
'TotP' 'volume'
'SURF' ' '
AF 'LocalDepth' 'surf'
0 ; no output is required for the dump file
2 ; all substances and extra output for the history file
11 ; number of extra variables
'NH3' 'volume'
....
'LocalDepth' 'surf'
2 ; all substances and extra output
11 ; number of extra variables
'NH3'
......
'LocalDepth'
1 ; binary history file 'on'
DR
9.1 General
D-Water Quality is able to produce a number of output files. The contents of some of them
can be steered with this input section. The time steps and / or time spans that are used for
the output files are given in group 2 of the input file. There the start time, stop time and time
step size of 3 types of files are given through:
⋄ the monitoring file timer
⋄ the map file timer
⋄ the history file timer
These timers will be called mon-timer, map-timer and his-timer respectively There are more
output files, but they all use one of these 3 timers.
This group of the input file steers the information that will be displayed in the files. By default
all concentrations of modeled substances are part of the output in a file. The concentrations
are expressed in mass/m3 for the transported substances and in mass/m2 for the passive
substances. It is however also possible to add information that is computed by the water
quality processes to the output files. Obviously useful extensions can be non-modeled derived
quantities like Chlorophyll (the model models individual algae species in mgC/l) or Secchi
depth. Especially in the set-up phase of a water quality model it is useful to also write output
on intermediate computation results like the actual growth and mortality of the algae species,
which is light and temperature dependent. This information is useful to check whether the
model acts as expected. Once production simulations have to be conducted these entries
Deltares 71 of 95
D-Water Quality, User Manual
can be removed from the output files if there is no specific interest for them any more. The
information that is added to the output files is added in exactly the same way as the modeled
substances. In this way it is possible to make time series graphs, color contour graphs or 3D
graphs of added variables as if they were modeled substances. Using the PLCT to select
water quality processes and model inputs that will be available for external steering, it is also
possible to view and select the quantities that can be added to the output files.
This is not the only location where the content of output files is determined:
⋄ The keyword section of group 2 of the input file contains a number of directives to switch on
the production of mass balance information. These directives may trigger the production
T
of additional output to standard output files and the production of separate files with output
of mass balance information. Although not directly steered by the input in this group, they
will nevertheless be briefly described here.
⋄ The monitoring area and monitoring transects section of group 2 of the input file allows
the definition of other monitoring locations than just a simple cell. The definition of these
AF areas and transects determines for which spatial locations additional output of time history
data will be given. The output will be added to the monitoring file and to the history file.
⋄ Group 10 of the input data deals with on-line statistics on variables. In this group it is
possible to define a number of statistics that have to be computed during the simulation.
The results of these statistics are saved either in the regular output files or in additional
output files that are described in that section of the manual.
D-Water Quality used to produce two types of output files for history and map data: the plain
binary files and the self-descriptive NEFIS files. Neither of these files contain any information
on the shape of the grid. Deltares is now in a process to migrate the NEFIS output to NetCDF
using the UGRID standard to describe the grid. It is now possible to replace the NEFIS map
DR
file by a NetCDF map file by specifying a file WAQGEOM file in group 3 of the input file.
72 of 95 Deltares
Model output
software of D-Water Quality. It contains time series at selected monitoring areas and
monitoring transects of concentration values and additional output variables. Also for the
history file it is important to have the correct weighing option from ’volume’ ’surf’ and none
(’ ’)
The history file start, stop and step timings are given values in input group 3.
The monitoring areas to write concentrations and additional output variables for are given
in input group 3.
4 the map output file (the .map file)
This is a binary output file that is readable using the standard graphical post processing
software of D-Water Quality. It contains complete fields of concentrations and additional
T
output variables for the selected time steps.
The map start, stop and step timings are given values in input group 3.
5 the balances output file (the -bal.his file and the -bal.prn file)
This is a user readable output file and a binary output file that is readable using the stan-
dard graphical postprocessing software of D-Water Quality. They contain all mass bal-
AF ances terms of the selected monitoring areas for the model concentrations.
The balances output file uses the start, stop and time step information from the monitoring
file.
6 the NEFIS or NetCDF history file (the .hda and .hdf files, or _his.nc file)
This file is equivalent with the binary history file and it uses the same timings. It is to be
superseded by a NetCDF file version of the history file (see 3).
7 the NEFIS or NetCDF map file (the .ada and .adf files, or _map.nc file)
This file is equivalent with the binary map file and it uses the same timings. It is to be
superseded by a NetCDF file version of the map file (see 3).
8 the statistical output map file (the -stat.map file)
This file has exactly the same structure as the binary map file. It starts to be processed
DR
at simulation start time, it stops at simulation stop time and uses the simulation time step.
The file contains spatially distributed statistical data that is defined in the group 10 of the
input file. The data is computed on the fly and may result in spatial fields of exceedence
frequencies, time averaged values, standard deviations etc.
9 the statistical monitoring file (the -stat.mon file)
This is a user readable output file with statistical characteristics of the simulation that
are not spatially distributed. It starts to be processed at simulation start time, it stops at
simulation stop time and uses the simulation time step.
10 the restart file (the .res file and the _res.map file discussed in the group 8 input sec-
tion)
It is to be expected that the writing of the _res.map file will be discontinued soon.
11 a -timers.out file that may assist in the analysis of computational performance of the
simulation.
Deltares 73 of 95
D-Water Quality, User Manual
If the integer is missing and directly #9 follows, then this group is absent and default output
processing (only modeled substances and their balances) will take place.
⋄ for each of four output file types:
the monitoring file
⋄ ⋄ ⋄ ⋄
T
0 no output is required for this file
1 default action is required for this file (output of modeled substances only)
2 the default output is required plus the items that are mentioned in the following listing
3 only the items that are mentioned in the following listing are required
The listing that should follow for integer values 2 and 3 consists of:
AF the number of additional variables
⋄ ⋄
Valid values are 0 to 9. The higher the number the more the data will be compressed,
using less disk space, but potentially requiring more processing time. The default level
is 2.
NCCHUNK value – specifies the so-called chunk size (NetCDF4 only). The chunk
⋄
size is given in bytes. See the documentation on NetCDF4 for more information. De-
fault: no chunking applied.
NCSHUFFLE value – specifies whether shuffling will be applied or not (NetCDF4
⋄
only). By default shuffling is off. If the value given is "YES", shuffling is turned on.
Note that the effectiveness of these compression options depends on many factors and it
is not possible to give rules of thumb for "best" use.
9.4 Finalization
This part of the input file is finalized with the #9 end of ninth data group indicator.
74 of 95 Deltares
10 Statistical output
This is the tenth group in the input file. This input group may read like:
version 3 minor 28
period 'annual'
suffix 'ann'
start-time '1997/01/01-00:00:00'
stop-time 'STOP'
T
end-period
output-operation 'STAQTL'
substance 'OXY'
suffix 'p10'
real-parameter 'CQLEV' 10
real-parameter 'NOBUCK' 20
DR
real-parameter 'CLOBND' 0
real-parameter 'CUPBND' 10
end-output-operation
output-operation 'STADSC'
substance 'OXY'
suffix ' '
end-output-operation
output-operation 'STADPT'
substance 'OXY'
suffix ' '
end-output-operation
output-operation 'STAGEO'
substance 'EColi'
suffix 'geo'
real-parameter 'THRESH' 1
end-output-operation
10.1 General
It is always possible to conduct statistics with the output files of D-Water Quality simulations.
You may read them and compute average values, standard deviations and percentiles of the
concentrations that you read. Besides the fact that this will necessitate you to write computer
programs yourself with all associated inconveniences, it may also be that the data in the files
are too sparse to conduct sensible statistics with. If you want to identify spatial patterns of
average values, standard deviations and excess percentiles, then the only suitable dataset is
the binary .map file. One complete record in the map file is already as large as the number
of substances and additional variables times the number of computational cells. This may be
Deltares 75 of 95
D-Water Quality, User Manual
a large amount and you may feel forced to limit the frequency of writing .map files. But then
you also limit the frequency of available data for statistical analysis.
To support you somewhat with your statistical analysis it is possible to let D-Water Quality
compute summary statistics on the fly, using every time step of the simulation, also those that
are not written to file. Input group 10 contains the input needed to use this facility. The input
has two distinct parts:
⋄ Definition of time intervals for statistical evaluations
⋄ Definition of the statistics wanted, together with for some of them the required and optional
coefficients
T
The statistical input may be preceded by the definition of a version number and a version
sub-number after the VERSION and the MINOR keywords respectively.
AF
10.2 Definition of time intervals
The definition of time intervalsStatistics!intervals has to follow the following rules:
⋄ They are enclosed by the PERIOD and the END-PERIOD keywords
⋄ Any number of time intervals may be defined, but you must be aware that all intervals are
used by all the statistics that work on intervals.
⋄ Intervals have a name that is specified immediately after the PERIOD keyword.
⋄ Intervals may have a suffix or abbreviation. This suffix is essential and should be unique
if you have multiple intervals. It is added to the name of the output variable to allow
for identification. The suffix should be brief, because otherwise the name of the output
variable will run out of space. The suffix is specified by the keyword SUFFIX followed by
DR
All specified intervals are applied for all the statistical procedures that work on intervals.
76 of 95 Deltares
Statistical output
T
file.
These statistics are evaluated for all defined periods in this input group.
The statistic requires a REAL-PARAMETER called THRESH, a threshold below which the
data are omitted.
⋄ Excess frequencies and Average during excess
AF Invoked with the keyword STAPRC.
The resulting two statistics are written to a separate -stat.map and -stat.mon file.
These statistics are evaluated for all defined periods in this input group.
The statistic requires two parameters:
a REAL-PARAMETER called CCRIT, the excess threshold.
⋄ ⋄
a LOGICAL-PARAMETER called ABOVE that can have value ’yes’ if frequency and
average above threshold should be computed and value ’no’ if frequency and average
below threshold should be computed.
⋄ Quantiles
Invoked with the keyword STAQTL
DR
Deltares 77 of 95
D-Water Quality, User Manual
They will have the 7 letter prefix DPTAVG_, DPTMIN_, and DPMAX_
⋄ Written to a separate D-Water Quality binary and Nefis -stat map file and the ASCII
T
monitoring file for
Maximum, Minimum, Mean and Standard deviation STADSC.
⋄
They will have the prefix MIN_, MAX_, MEAN_ and STDEV_.
Excess frequencies and Geometric means with and without threshold value STAGEO.
⋄
10.6 Finalization
This part of the input file is finalized with the #10 end of tenth data group indicator.
DR
78 of 95 Deltares
11 Annexes
T
for time series of concentrations at open boundaries.
for time series of loads of substances through rivers and outfalls.
for time series of process steering functions or segment functions.
⋄ for the start and stop times of run-time statistics evaluation.
AF You may also need to provide time step sizes to D-Water Quality:
⋄ for the integration procedure.
⋄ for the writing of output files.
⋄ to specify time lags or time delays.
The Julian date of the Calendar offset is subtracted from this value
The difference is converted to relative system time units
The important advantage of this procedure is that months and years have their correct
amounts of days and that you can input real dates.
If other input than an integer or a valid calendar time string is provided, several things can
happen:
⋄ If a real value is encountered then either:
A context dependent path is chosen to interpret the real value in a sensible way, like a
⋄
Deltares 79 of 95
D-Water Quality, User Manual
concentration or a coefficient if the local context allows such an item to appear at that
location in the file.
⋄ An error is produced stating that a real value was found whereas an integer or a string
was expected. This happens if a real value cannot appear according to the local
context of the file.
⋄ If a string is encountered that does not equal to a valid calendar time string, then either:
A context dependent path is chosen to interpret the string in a sensible way, like the
⋄
T
An error is produced stating that the string read was not a valid calendar time string.
⋄
This happens if a string value cannot appear according to the local context of the file.
Be aware that:
AF ⋄ the system time values are stored in a 32-bits signed integer and can thus only run from
-68 years to +68 years.
⋄ the DDHHMMSS format has a highest value of 231 = 2147483648 or 5 years of 365 days
and 322 days, 48 hours, 36 minutes and 48 seconds.
⋄ the YYDDDHH format is only limited by the -68 to +68 years time window.
cate the specific structure of the binary files that will be used in this description.
an integer indicating the number of lines that should be read from the multiple hyd
⋄
file.
an integer interpolation option in time, between the records in the files with 1 is no
⋄
or ’vert-diffusion-file’. This string should correspond exactly with the file that is to
be used from the files that are listed in the .hyd file. Also for the salinity, temper-
ature chezy coefficients, shear stresses or suspended sediments as computed by
the hydrodynamic model it is possible to follow this procedure by mentioning the
corresponding keyword from the .hyd file.
the name of the multiple hyd file to be used.
⋄
-2 A binary external file will be used that will be interpolated between its records. This op-
tion number can optionally be followed by the keywords UNFORMATTED and BIG_ENDIAN
and should be followed by the file name to be used.
-1 This is the same as the INCLUDE directive (its ’old-style’ predecessor) that should be
followed by and ASCII input file name to switch input processing to.
0 A binary external file will be used with one time step per record. This file will not be in-
terpolated. This option number can optionally be followed by the keywords UNFORMATTED
and BIG_ENDIAN and should be followed by the file name to be used.
1 ASCII input will follow in this file.
Any other option number will result in an error message. If the option number was zero,
then the input is done. The information will be read from the specified file. Input is also
done if the option number was -4 or -2 and the subject of this reading was not dispersions.
⋄ If dispersions are to be read, the following is required:
80 of 95 Deltares
Annexes
three real values as scale factors for the dispersions in the three directions.
⋄ ⋄
three real values that contain the yet unscaled values of the dispersions in the three
directions.
⋄ ASCII input if the first option was -1 or 1
This input starts with a data option number:
1 Information is constant and input will be provided without defaults:
For all of the three directions that have non-zero number of exchanges the following
should be provided:
T
A scale factor for this direction.
⋄ ⋄
A matrix of data with as columns (fastest running index) the number of values to be
read per volume or exchange with for each of the number of volumes or exchanges
in this direction a row with the unscaled values.
The scale factor is applied to all specified values in its direction.
AF2 Values are constant and input will be provided using default values:
For all of the three directions that have non-zero number of exchanges the following
should be provided:
A scale factor for this direction.
⋄ ⋄ ⋄
For each of the required values per volume or exchange, an unscaled default value.
A number of overridings (exceptions to the default settings) plus that many sets of:
◦ An exchange number that should be overriden with the exceptional values.
◦ For each of the required values per volume or exchange an unscaled excep-
tional value.
DR
The scale factor is applied to all specified default values and exceptional values in its
direction.
3 Information comes as time functions:
Now for all volumes or exchanges time functions are specified through ASCII input
for all required values. This happens using the standard ’old-style’ feature for input
processing of time functions that is hardly used any more. The input is structured in
input blocks that all start with an integer option number:
1 Information in this block is given at breakpoints as a block function (no linear
interpolation)
an integer giving the number of items (exchange numbers or segment num-
⋄
◦ either an absolute time string, or a time integer indicating the time stamp
of this breakpoint.
◦ a matrix with values per breakpoint.
The matrix has 1 column for the reading of volumes, areas and flows.
It has 2 columns for the reading of the ’from’ and ’to’ lengths and it has
as much columns as there are additional velocity and dispersion arrays
specified for the reading of additional velocities and dispersions.
The rows in the matrix are the items that are contained in this input block.
2 Information in this block is given at breakpoints, interpolation will be linear.
Deltares 81 of 95
D-Water Quality, User Manual
The input structure and type of input information for this option is exactly equal
to that of option 1.
3 Information in this block is given as a set of harmonic functions.
an integer giving the number of items (exchange numbers or segment num-
⋄
bers for hydrodynamics) that will be contained in this input block.
⋄ ⋄ the item numbers of the items that are contained in this input block.
an integer giving the number of harmonic components that will be read, ex-
clusive of the zeroth component, the average value of the series.
for each item in this block the average value of the harmonic series.
⋄ ⋄
T
for each harmonic component:
◦ an integer period of the harmonic component (in units of the system
clock).
◦ a real value giving the phase of this component.
This real value can be between -0.5 and +0.5 with no phase shift at value
AF 0.0. It can equally well be between 0.0 and 1.0 with no phase shift at
values 0.0 and 1.0. This does not matter because the harmonic function
is cyclic and the phase shift is expressed as fraction of the period of the
component.
◦ a matrix with amplitude values of the component.
The matrix has 1 column for the reading of volumes, areas and flows.
It has 2 columns for the reading of the ’from’ and ’to’ lengths and it has
as many columns as there are additional velocity and dispersion arrays
specified for the reading of additional velocities and dispersions.
The rows in the matrix are the items that are contained in this input block.
DR
an integer giving the number of Fourier components that will be read, exclu-
sive of the zeroth component, the average value of the series.
an integer giving the base period, the period of the first Fourier component
⋄ ⋄ ⋄
for each item in this block the average value of the Fourier series
for each Fourier component:
◦ a real value giving the phase of this component.
This real value can be between -0.5 and +0.5 with no phase shift at
value 0.0. It can equally well be between 0.0 and 1.0 with no phase shift
at values 0.0 and 1.0. This does not matter because the Fourier function
is cyclic and the phase shift is expressed as fraction of the period of the
component.
◦ a matrix with amplitude values of the component.
The matrix has 1 column for the reading of volumes, areas and flows.
It has 2 columns for the reading of the ’from’ and ’to’ lengths and it has
as much columns as there are additional velocity and dispersion arrays
specified for the reading of additional velocities and dispersions.
The rows in the matrix are the items that are contained in this input block.
82 of 95 Deltares
Annexes
T
that form together a hydrodynamic dataset are generally described in an ASCII .hyd file like
is produced by Delft3D-FLOW or Telemac. This means that a multiple hyd file just needs to
refer to these .hyd files. An example is in a real-life marine application:
The reference to the multiple hyd file starts with 2 integers in the calling input file:
⋄ The number of lines to be used in the multiple hyd file (would be 7 in our example).
⋄ The interpolation option that can be:
0 for block wise interpolation in time (flows and areas).
1 for linear interpolation in time (volumes).
2 for linear interpolation of the logarithms of the file values block wise in time (vertical
diffusions).
Deltares 83 of 95
D-Water Quality, User Manual
3 for linear interpolation of the logarithms of the file values both between files and in
time.
T
file is reached during the period.
⋄ At the end of the period the description for the next period is used.
⋄ Should the simulation extend beyond the specification periods in the multiple hyd file, then
the whole multiple hyd file is rewound and executed again.
⋄ For a check it is strongly advised to output at several locations the time series of water
AF ⋄
levels for inspection.
Both if rewound and if specifications change, the presence of the CLOSE_ERR constant
determines whether the concentration will show a (small) jump or whether the mass will
do.
standard for that language however does not support binary files. FORTRAN supports unfor-
matted files. These are also very efficient to read but they have record information included in
the file. This record information is compiler specific so although a standard exists for the unfor-
matted file in the FORTRAN language, the contents of that file may vary per implementation.
If you are using the same compiler for your hydrodynamic program as was used for our D-
Water Quality source code, then there are not so much problems. Before mentioning the name
of your binary file in the input file you just give the keyword UNFORMATTED and D-Water Qual-
ity will open and read the file as an unformatted file. If you are using a very recent compiler,
you may open and write your hydrodynamic files with the ACCESS = 'STREAM' option in
your source code. That is more or less equivalent with the binary files that D-Water Quality is
reading normally.
Binary files consist of bit patterns indicating the numbers rather than readable characters.
There are several bit patterns around to write integer and real numbers. D-Water Quality is
using the IEEE standard with ’little endian’ layout of the bytes. That is the common layout on
PC type of processors. Main frames and workstations may be equiped with processors that
use the ’big endian’ layout of bytes. If you are facing those files you may also use the keyword
BIG_ENDIAN before you specify the name of the binary file to be read by D-Water Quality.
In the following a documentation of the contents of the binary files that are directly read by D-
Water Quality is given. This specification also mentions the batches of data that D-Water Qual-
ity reads from them separately. This would normally not be of importance. As long as you
have written your data in the same order in the binary file, then it does not matter in what
chunks D-Water Quality reads them. This is however not the case for unformatted files. They
contain record information and the chunks used for reading need to be exactly identical to
the chunks used for writing. To support you with that the specification contains the reading
procedure.
84 of 95 Deltares
Annexes
The table 11.2 gives a list of binary files that are read directly by D-Water Quality. Each • in-
dicates a new record for unformatted files. The matrices (nn, mm) indicate nn ∗ mm values
with the nn index running fastest. The capital amounts refer to the dimensions mentioned in
the corresponding sections of theis manual:
Variable Legenda
T
NOSEG Number of computational cells
NSEGFUN Number of segment functions that are defined for this file
Note: the matrix is transposed for this file
Table 11.2: Documentation of the binary input files that can be read directly by D-
Water Quality
File Records
plot grid segment proper- • NOSEG integer*4, one for each segment
ties
Deltares 85 of 95
D-Water Quality, User Manual
File Records
T
flows • ’time’ integer*4, NOQT real*4 values
• same for next time step(s)
• ···
AF
exchange areas • ’time’ integer*4, NOQT real*4 values
• same for next time step(s)
• ···
86 of 95 Deltares
Annexes
Deltares, 2016. “BIBTEX key with no entry, needed if no citations are made in the document.”
T
AF
DR
Deltares 87 of 95
D-Water Quality, User Manual
T
AF
DR
88 of 95 Deltares
Index
Active ASCII input, 2
cells, 30, 34, 85 available, 76
exchanges, 34 blocks, 46, 52, 59
grid, 29, 36, 85 bulky table, 5
processes, 59 constant, 81
substances, 3, 9, 45, 50, 67 Fourier series, 82
Advection-diffusion equation, 3, 30, 38 grid mapping, 24
Aggregation file, 24 harmonic functions, 82
Attributes, 29 hydrodynamic flow, 1, 30, 37
T
interpolation, 81
Binary files, 4, 8, 27, 36, 62, 68, 75, 80, 84, matrix of, 47
85 missing, 52
Blank lines, 5 numerus equal, 5
Block interpolation, 30, 48, 54, 63 option, 81
AF
Boundary, 43
cell, 36
concentrations, 45
readability of, 9
statistics, 75
time function, 81
conditions, 2, 43, 50 Diagnostics
ID, 44 levels, 5, 8
name, 44 output, 5, 6
time lags, 45 line length, 7
type, 44
run time, 72
Calendar simulation settings, 72
dates, 47, 54 DIDO grid tool, 17
DR
Deltares 89 of 95
D-Water Quality, User Manual
T
include, 5, 22 rectilinear, 35
interpolated, 80 reference, 24
listing, 44, 50 regular, 35, 37
little endian, 36 structured, 1, 37
map, 18 sub-grid, 23
AF monitoring, 18
multiple hyd, 31
ODS, 48, 62
tool DIDO, 17
topology, 72
unstructured, 1, 39
output, 3, 7, 57 unstuctured, 33
sample input, 1 water, 68
type options, 80 Group, 2
unformatted, 36, 62
Finite Volume Method, 4 History file
Finite Volumes Method, 43, 49 binary, 72
Floating point, 5 NEFIS, 73
DR
Flows, 1, 2, 4, 13, 30, 33, 34, 39, 43, 49, timer, 18, 71
51, 52 Horizontal surface area, 61
Flux, 3, 10, 13 Horizontal surface area, 39, 50, 61, 74
advective, 13
correction, 13, 43 Include, 5, 27
diffusive, 13, 35, 38, 40, 50 directive, 5, 37, 59, 73, 80
exchange, 34 file, 5, 17, 22, 30, 55, 59
net, 17 nesting, 5
vertical, 39 Initial conditions, 67
Free formatted, 5 Z-layer models, 61
Function, 2, 4, 6, 58, 63, 79 INITIALS keyword, 69
block, 63 Input
breakpoints, 16 block, 45, 51, 64, 70
Fourier, 64 computations, 47, 53
harmonic, 63 Input file, 1, 4, 7, 12, 24
linear, 63 first form, 34
segment, 37, 50, 58, 65 form, 34
Thatcher Harleman, 45 line length, 7
time, 58, 76 second form, 41
version number, 7
Graphical User Interface, 9, 17, 24, 50, 57 Input group, 1
Grid, 21 Integers, 5
active, 36, 37 Integration
base, 21, 22 option, 12
bottom, 23, 68 procedure, 12
cell, 6, 8, 16, 34, 52, 58, 69 start time, 16
computational, 22 stop time, 16
definition, 23 time step, 16, 61
direction, 37 constant, 16
90 of 95 Deltares
INDEX
T
Layered bed, 22, 23, 63, 67, 68, 70 parameters, 58
Lengths, 35, 40, 81 segment functions, 58
Linear interpolation, 30, 48, 51, 54, 63, 80, switching ’on’, 57, 59
83 timestep, 26
transport, 3, 39
AF
Map file, 75, 78
binary, 73
NEFIS, 73
water quality, 3, 9, 11, 28
Deltares 91 of 95
D-Water Quality, User Manual
T
System time, 8, 11, 79
Systems, 9 Velocities, 2, 39
additional, 4, 34, 35, 39, 81
Tabs, 1 computed, 38
Technical reference manual, 57 in cell midpoints, 39
AF
Time
absolute, 8, 55, 64, 65, 81
breakpoints, 16, 64, 65, 79, 81
Volumes, 2, 4, 22, 30, 33, 40, 67, 80, 83
amount of, 21, 30
file, 31
integer, 12, 16, 64, 65, 79, 81 values, 30
maximum value, 12, 80
series, 16, 30, 45, 47, 51–53, 60, 64, Water bed, 3, 9, 10, 22, 33, 50, 67, 70
65, 72, 79, 84 Water column, 3, 70
string, 8, 12, 47, 54, 64, 79 bottom, 29
tokens, 31, 79 top, 29
Timers, 11 Word processor, 1
auxiliary, 11
DR
92 of 95 Deltares
DR
AF
T
T
AF
DR