This WiKi page briefly describes the Delft3D model adapter for Delft-FEWS. This model adapter presently supports the following modules from the Delft3D suite:

• Delft3D-FLOW
• Delft3D-WAQ (Delwaq)
• Delft3D-WAVE
• Delft3D-PART

In order to use the adapter some knowledge of both Delft-FEWS and Delft3D is required.

1. Directory structure

To minimise the number of choices that have to be made by the user, the Delft3D adapter expects a fixed set of directories and files. Roughly speaking: anything for which a reasonable default can be set, has been fixed. This means for example that the description of the export activities in the Delft-FEWS configuration files must use these directory and file names. The advantage is that there are much less opportunities for making mistakes (see the section on configuration errors).

The following directories and files are used. The directories are taken as subdirectories of the <rootDir> that you give in the configuration of the general adapter module.

2. Configuration file

The Delft3D adapter uses a fixed set of directories and files to do most of its work. Some items do have to be specified in a separate configuration file (to be placed in the root of the <rootDir>), as these may vary from application to application. This section describes the structure of the configuration file.

Below is an example of such a [file:
]

<?xml version="1.0" encoding="UTF-8"?>

<delft3dModel xmlns="http://www.wldelft.nl/fews"

              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

              xsi:schemaLocation="http://www.wldelft.nl/fews

              http://fews.wldelft.nl/schemas/version1.0/delft3DModel.xsd">

       <general>

              <description>Example of a configuration file for Delft3D: Delft3D-FLOW,

full run</description>

              <module>FLOW</module>

              <runId>exm</runId>

              <workDir>../flow</workDir>

              <modelDir>../flowtpl</modelDir>

              <auxiliaryGridFile>hirlam.grd</auxiliaryGridFile>

              <geoDatum>WGS_1984</geoDatum>

              <timeZone>1.0</timeZone>

       </general>

       <preAdapter>

              <steeringTimeSeriesName>H/BOUNDARY_1</steeringTimeSeriesName>

       </preAdapter>

       <postAdapter>

              <timeSeriesOutput>

<timeSeries parameter="Water level" location="Station 1"

              fewsParameter="Water level" fewsLocation="Station 1"/>

<timeSeries parameter="Depth-averaged velocity" location="Station 1"

              fewsParameter="Waterlevel" fewsLocation="Station 1"/>

<timeSeries parameter="U velocity" location="Station 1" layer="1"

              fewsParameter="U velocity"

fewsLocation="Station 1 – layer 1"/>

...

              </timeSeriesOutput>

              <mapOutput>

<map parameter="U velocity" layer="1"

              fewsParameter="U velocity" fewsLocation="Layer 1"/>

<map parameter="U velocity" layer="1"

              fewsParameter="U velocity" fewsLocation="Layer 1"/>

                     ...

       </postAdapter>

</delft3dModel>

The file consists of three sections:

• <general>: General information that should always be present.
• <preAdapter>: Information for the preadapter step (in which the input files are prepared). This section is optional – for instance, if the preparation is done in another step.
• <postAdapter>: Information for the step after the actual computation where the results are exported to Delft-FEWS. This section is also optional.
  

Each section will now be described in more detail.

Section: <general>

Because Delft3D consists of several modules that can be used in different configurations, it is necessary to specify which module should be run (the keyword module). This module (either FLOW, WAQ, ECO, PART or WAVE) determines together with the string specified as the run-id (keyword runId) which files will be used (see the table below).

The keyword workDir indicates in which directory the computational programs will start and the keyword modelDir should refer to the directory containing the template files and the other (fixed) files that together make up the input for the computation.

With these four keywords the user should be able to define the characteristics of most if not all runs of Delft3D modules.

Both Delft3D-FLOW and Delft3D-WAQ (and therefore Delft3D-ECO as well) require the name of a grid file (the keyword auxiliaryGridFile):

• Delft3D-FLOW requires the name of the file (*.grd) that defines the grid for the meteorological data. It is written in the header of the file with air pressure and so on.
• Delft3D-WAQ requires the name of the LGRID and CCO files, so that the segment function files can be written properly. This information is needed by the postadapter as well, in order to export the results on a grid. To avoid duplication, the information is given in the general section.
  

The entries geoDatum and timeZone are optional, they default to respectively "WGS_1984" and "GMT".

Section: <preAdapter>

The <preAdapter> section contains one keyword only, the name of the timeseries (found in the timeseries exported by Delft-FEWS) that is to be used as to determine the time frame of the simulation.

The reason for this keyword is that Delft-FEWS leaves it to the computational programs to determine what the actual period is that should be simulated. As in Delft3D the timeseries can usually span any period and the start and stop times of the computations are given independently of any timeseries, there needs to be a mechanism to connect the two philosophies.

The name of the timeseries is to be formed in this way: "external name of the parameter/external name of the location". For instance: if the external parameter name is "H" and the location is "Southern boundary", then the name for that time series is: "H/Southern boundary".

Note:

This convention for constructing the names of the time series that are found in the files exported by Delft-FEWS is used throughout the adapter – see for instance the section describing the keywords.

Section: <postAdapter>

The section <postAdapter> describes the actions to be taken after completion of the model run. Rather than blindly export all the results from the model run to Delft-FEWS and let it pick up the timeseries and map stacks of interest, the adapter exports only those timeseries and map stacks described in this section.

It also translates the names used by Delft3D into names known by Delft-FEWS, so that for the timeseries you specify the parameter names and the location names as seen in Delft3D-GPP (the adapter uses the same library as Delft3D-GPP to read the result files).

For parameters defined per layer you must specify the layer as well as the location.

For map stacks you specify the parameter and the layer for which the results are to be transferred to Delft-FEWS (Delft-FEWS currently only handles two-dimensional data).

Template files and keywords

In the table below the various keywords are explained. It is important to note that these keywords are filled whenever they are encountered in a template file – the keywords are not associated with a particular type of file. The format for the keywords and any arguments there may be is as follows:

$(keyword: argument1, argument2, ...)

or, if there are no arguments:

$(keyword)

(Technical note: the entire text from the opening "$(" to the trailing ")" is replaced, without a trailing new line, by whatever the contents should be. The arguments should not contain commas parenthesis and there should be at least one space after the comma. This syntax makes it easy to implement the template mechanism.)

Configuration errors

The adapter checks for the following types of errors:

• Are any of the timeseries and map stacks found in the input directory not used in the input for the Delft3D module? (This would mean some timeseries was forgotten in the template files.)
• Are all the timeseries and map stacks as encountered in the template files indeed available from the export by Delft-FEWS? If not, the proper data can not be filled in in the files and the computation can not run properly.
• Do all timeseries filled in in a particular table have the same start and stop time and the same time step? (The adapter does not attempt to correct any mismatch – this should be done via the Delft-FEWS configuration)

Technical documentation

This section describes the actual implementation of the adapter. It is meant mainly to help the implementors.

The class Delft3DPreAdapter has the following task:

• Copy the files found in the template directory to the work directory.
• Identify for which module the input should be prepared and call upon the specific class for that module to identify the keywords in the files and provide suitable replacements.
• Scan all input files and replace the keywords (more precisely: the text "$(...)") by the text given by the specific preadapters.
  

(This way we have a very general mechanism to manipulate input files based on templates)

The preadapter classes that are specific to the Delft3D modules may prepare other files as well, especially files that have to be written from the start: the files containing the mapstacks are a prime example for this.

The class Delft3DPostAdapter takes care of processing the output files from the various Delft3D modules in response to the instructions found in the configuration file. As use is made of a general library (the same as used in Delft3D-GPP), the details are all hidden and the post adapter code is fairly compact.

There are a few details particular to the Delft3D modules:

• Delft3D-FLOW produces, in general, a series of restart files. Only the last one is made known to FEWS.
• Delft3D-PART does not have initial conditions files or restart files.
• Delft3D-WAQ produces a restart file at the end of the computation.
• P.M.: Delft3D-WAVE
  

Note that to keep the interaction between the preadapter and the post adapter at a minimum (the preadapter handles the start and stop time for the computation and the post adapter needs to know the stop time to properly register the restart files), we use a small auxiliary file containing that information.[[1]|#_ftn1]

[[1]|#ftnref1] Strictly speaking, for Delft3D-FLOW the time that we need is the time of the _last restart file. This has not been implemented yet – if you use the FLOW_TIME_RST keyword, this should not matter.