Delft3D adapter

This page briefly describes the Delft3D model adapter for Delft-FEWS, using an XML run file. There is also a Delft3D adapter with NetCDF run file.

The model adapter described here supports the following modules from the Delft3D suite:

Delft3D-FLOW
Delft3D-WAQ (Delwaq)
Delft3D-WAVE
Delft3D-PART
D-Flow FM (see also D-Flow FM adapter)

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.

Directory/file	Purpose
input	Contains all the files with timeseries and map stacks exported by Delft-FEWS
input/timeseries.xml	XML-file with (scalar) timeseries
input/map_<param>.xml	XML-file describing the map stacks with parameter "param" (see the documentation of the keywords)
stateInput	Contains all the files with the initial conditions and other static information that together constitute the "state" from which the computation must start
stateInput/export_states.xml	The XML-file describing the time of the state files. (Export from the point of view of Delft-FEWS)
output/timeseries_<runId>.xml	XML-file with the resulting (scalar) timeseries, to be imported by Delft-FEWS
output/fewsParameter>.xml	XML-file describing the resulting map stacks with Delft-FEWS parameter "FEWS-param" (see the documentation of the keywords)
stateOutput	Contains all the files with the final results, useful as initial conditions.
stateOutput/import_states.xml	The XML-file describing the time of the final state files. (Import from the point of view of Delft-FEWS)

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.

The configuration file consists of three sections, general, pre-adapter and post-adapter. For example:

 <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">
 <description>DCSMV5 FLOW</description>
 <general>
    <module>FLOW</module>
    <runId>dcsm98</runId>
    <workDir>workDir</workDir>
    <modelDir>Repo_dcsmv5</modelDir>
    <auxiliaryGridFile>1953.grd</auxiliaryGridFile>
    <fieldFileFormat>new</fieldFileFormat>
    <outputTimeSeriesInOneFile>true</outputTimeSeriesInOneFile>
 </general>
 <preAdapter>
    <steeringTimeSeriesName>H.profile/dcsmv5</steeringTimeSeriesName>
 </preAdapter>
 <postAdapter>
    <timeSeriesOutput>
       <timeSeries parameter="water level" location="ABDN" layer="1" fewsParameter="H.simulated" fewsLocation="aberdeen"/>
       <timeSeries parameter="water level" location="AUKFPFM" layer="1" fewsParameter="H.simulated" fewsLocation="aukfield_platform"/>
       <timeSeries parameter="water level" location="DELFZL" layer="1" fewsParameter="H.simulated" fewsLocation="delfzijl"/>
       <timeSeries parameter="water level" location="DENHDR" layer="1" fewsParameter="H.simulated" fewsLocation="den_helder"/>
    </timeSeriesOutput>
    <mapOutput>
       <map parameter="water level" layer="1" fewsParameter="H.simulated" fewsLocation="dcsmv5"/>
    </mapOutput>
 </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.

2.1 Section: <general>

In the <general> section the following options can be specified:

Keyword	Value	Description
general	FLOW, WAQ, PART, WAVE	String indicating the type of Delft3D module
runId		String used to identify the template input file. Relevant input files for each Delft3D module are listed below.
stateFileId		Prefix of the state file filename
workDir		Directory where the computational models will run
modelDir		Directory containing the template files (static model input). These files are copied to the workDir by the model adapter prior to running a simulation.
auxiliaryGridFile		See below.
fieldFileFormat		Control the format of the meteo and other field files (Check)
outputTimeSeriesInOneFile		Copies all output timeseries to one output XML file if true. (Check)
geoDatum		Indication of the coordinate system used for the output XML files by the postAdapter (defaults to WGS-1984).
timeZone		Indication of the time zone used for the output XML files by the postAdapter (defaults to GMT).
online	MORPHOLOGY	Copies extra morphology files for the FLOW pre- and post-adapter
rstNcFileSubscript		Specifies the extension for restart files in case of Deft3D-FLOW Flexible Mesh
warnAboutUnusedSeries		If true, give a warning about timeseries that are specified but not used. If false, an informational message is given instead

See the XSD schema file for more background information.

The runId used specified in the <general> section is used by the preAdapter to determine which files to scan for placeholder keywords (see below).

Module	Template files	Purpose
FLOW	<runid>.mdf <runid>.bcc, .bct, .dis, ...	Master definition file Various attribute files
WAQ, ECO	<runid>.inp couplnef.inp	Main input file, the only file that is supposed to contain keywords for this module. Input file for the coupling program.
PART	<runid>.inp	Like WAQ
WAVE	<runid>.mdw
FLOW_FM	<runid>.mdu	see http://publicwiki.deltares.nl/display/MD/D-Flow+FM+model+adapter

Both Delft3D-FLOW and Delft3D-WAQ 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.

2.2 Section: <preAdapter>

The <preAdapter> section contains one keyword only, the name of the timeseries (found in the timeseries XML file 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".

2.3 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. The names as used by Delft3D are similar to the names used in Delft3D-GPP (since the same ods.dll library is used to parse the data). See the below examples for reference. If names are not included in this overview, they can be obtained in the following way: 1) Start Delft3D-GPP, 2) Load the Delft3D data into GPP for the relevant parameter, 3) save the GPP case file, 4) open the GPP case file and use the parameter name as specified.

Note that if the <fewsParameter> and <fewsLocation> names match those names used in Delft-FEWS, no addition IdMapping is required upon importing the data in the general adapter (using <enableOneToOneMapping/> option in IdMap file).

For parameters defined per layer you must specify the layer as well as the location. Note that as Delft-FEWS only handles two-dimensional data (time,x,y). The layer number (z dimension) can be included as either a qualifier or childLocations in Delft-FEWS.

Command-line option -swapNorthSouth

Since 2013.02 there is an option to swap north and south in the Delft3DPostAdapter for regular grids.

			<executeActivity>
				<description>Delft3D Adapter</description>
				<command>
					<className>nl.wldelft.fews.adapter.delft3d.Delft3DPostAdapter</className>
				</command>
				<arguments>
					<argument>%ROOT_DIR%</argument>
					<argument>AGM.Flow.HC.xml</argument>
					<argument>-swapNorthSouth</argument>
				</arguments>
				<timeOut>10800000</timeOut>
				<overrulingDiagnosticFile>%ROOT_DIR%/diagnostics/delft3dpostadapter.xml</overrulingDiagnosticFile>
			</executeActivity>

Command-line option -skipFirstTimeStep

In 2013.02 a command line option was added to skip the first timestep of a forecast in the Delft3DPreWaveAdapter. This is to be used for forecasts only so that the warm state will be picked up correctly.

Export types

The postAdapter will export scalar timeseries to the XML file timeseries_<runId>.xml. 2D maps are exported to ArcInfo ASCII files names <fewsParameter>.xml.

For reference see the following examples:

Delft3D-FLOW (example):

<timeSeries parameter="water level" location="ABDN" layer="1" fewsParameter="H.simulated" fewsLocation="aberdeen"/>
<timeSeries parameter="dpt. aver. cur. mag" location="STN.1" layer="1" fewsParameter="C.speed.simulated" fewsLocation="UP.STN.1"/>
<timeSeries parameter="Temperature" location="STN.1" layer="19" fewsParameter="T.simulated" fewsLocation="UP.STN.1.L19"/>
<map parameter="dpt. aver. cur. v" layer="1" fewsParameter="V.simulated.u" fewsLocation="Delft3DFLOW_UP"/>
<map parameter="dpt. aver. cur. u" layer="1" fewsParameter="V.simulated.v" fewsLocation="Delft3DFLOW_UP"/>
<map parameter="Temperature" layer="19" fewsParameter="T.simulated.L19" fewsLocation="Delft3DFLOW_UP.L19"/>
<map parameter="Temperature" layer="18" fewsParameter="T.simulated.L18" fewsLocation="Delft3DFLOW_UP.L18"/>

Delft3D-WAQ (example):

<timeSeries parameter="APHANIZO" location="Stn_1 (1)" layer="1" fewsParameter="APHANIZO.simulated" fewsLocation="UP.STN.1.L1.WQ"/>
<timeSeries parameter="Chlfa" location="Stn_1 (1)" layer="1" fewsParameter="Chlorophyll.simulated" fewsLocation="UP.STN.1.L1.WQ"/>
<timeSeries parameter="EColi" location="Stn_1 (1)" layer="1" fewsParameter="E Coli.simulated" fewsLocation="UP.STN.1.L1.WQ"/>
<timeSeries parameter="EnCoc" location="Stn_5 (1)" layer="1" fewsParameter="Entero.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="FColi" location="Stn_5 (1)" layer="1" fewsParameter="F Coli.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="FDIATOMS" location="Stn_5 (1)" layer="1" fewsParameter="FDIATOMS.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="GREENS" location="Stn_5 (1)" layer="1" fewsParameter="Greens.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="IM1" location="Stn_5 (1)" layer="1" fewsParameter="IM1.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="IM2" location="Stn_5 (1)" layer="1" fewsParameter="IM2.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="MICROCYS" location="Stn_5 (1)" layer="1" fewsParameter="MICROCYS.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="NH3" location="Stn_5 (1)" layer="1" fewsParameter="NH3.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="NH4" location="Stn_5 (1)" layer="1" fewsParameter="NH4.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="NO3" location="Stn_5 (1)" layer="1" fewsParameter="NO3.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="OSCILAT" location="Stn_5 (1)" layer="1" fewsParameter="OSCILAT.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="OXY" location="Stn_5 (1)" layer="1" fewsParameter="OXY.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="PO4" location="Stn_5 (1)" layer="1" fewsParameter="PO4.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="POC" location="Stn_5 (1)" layer="1" fewsParameter="POC.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="Phyt" location="Stn_5 (1)" layer="1" fewsParameter="Phyt.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="SO4" location="Stn_5 (1)" layer="1" fewsParameter="SO4.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="SS" location="Stn_5 (1)" layer="1" fewsParameter="SS.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="SUD" location="Stn_5 (1)" layer="1" fewsParameter="SUD.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="Salinity" location="Stn_5 (1)" layer="1" fewsParameter="Salinity.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="SecchiDept" location="Stn_5 (1)" layer="1" fewsParameter="SecchiDept.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="Si" location="Stn_5 (1)" layer="1" fewsParameter="Si.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="TOC" location="Stn_5 (1)" layer="1" fewsParameter="TOC.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="Temp" location="Stn_5 (1)" layer="1" fewsParameter="T.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="TotN" location="Stn_5 (1)" layer="1" fewsParameter="TNitrogen.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="TotP" location="Stn_5 (1)" layer="1" fewsParameter="TPhosphate.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="TotalDepth" location="Stn_5 (1)" layer="1" fewsParameter="TotalDepth.simulated" fewsLocation="UP.STN.5.L1.WQ"/>
<timeSeries parameter="pH" location="Stn_5 (1)" layer="1" fewsParameter="PH.simulated" fewsLocation="UP.STN.5.L1.WQ"/>

Delft3D-WAVE (example):

<map parameter="Mean wave direction" layer="1" fewsParameter="Wave.direction.mean.ext" fewsLocation="Guanabara.wave.ext"/>
<map parameter="Mean wave period" layer="1" fewsParameter="Wave.period.mean.ext" fewsLocation="Guanabara.wave.ext"/>
<map parameter="Peak wave direction" layer="1" fewsParameter="Wave.direction.peak.ext" fewsLocation="Guanabara.wave.ext"/>
<map parameter="Peak wave period" layer="1" fewsParameter="Wave.period.peak.ext" fewsLocation="Guanabara.wave.ext"/>
<map parameter="Sign.wave height" layer="1" fewsParameter="Wave.sign.height.ext" fewsLocation="Guanabara.wave.ext"/>

Delft3D-PART (example):

For PART the option <formatForPart>NEFIS</formatForPart> has been added to switch converting the model output from the binary map files to the NEFIS map files, because the binary map files do not support file sizes above 2GB and NEFIS map files do.

	<postAdapter>
		<mapOutput>
			<formatForPart>NEFIS</formatForPart>
			<map parameter="Oil" layer="1" fewsParameter="Oil.simulated.L1" fewsLocation="delwaq.nonaggregated.L1"/>
			<map parameter="localdepth" layer="20" fewsParameter="WaterDepth.sim" fewsLocation="delwaq.nonaggregated"/>
			<map parameter="Oil disp" layer="1" fewsParameter="Oil.dispersed.simulated.L1" fewsLocation="delwaq.nonaggregated.L1"/>
			<map parameter="Oil disp" layer="2" fewsParameter="Oil.dispersed.simulated.L2" fewsLocation="delwaq.nonaggregated.L2"/>
			<map parameter="Oil disp" layer="3" fewsParameter="Oil.dispersed.simulated.L3" fewsLocation="delwaq.nonaggregated.L3"/>

For examples, see the adapterConfiguration_example_*.xml files attached to this WiKi page.

3. 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.)

Keyword	Description
FLOW_TIME_START	Start of the simulation (format in accordance with Delft3D-FLOW). (This is actually the time in minutes since the reference time, found in the mdf-file)
FLOW_TIME_STOP	Stop of the simulation (format in accordance with Delft3D-FLOW) (Ditto as the start time)
FLOW_TIME_RST	Duration of the simulation – useful for setting the time interval of writing the restart files so that only one restart file is written at the end of the simulation.
FLOW_TIMESERIES	Placeholder to fill in the timeseries in the so-called tim format (only the time and data, not the header). The keyword should be followed by the names of all timeseries that should be filled in there, separated by a comma and one or more spaces: $(FLOW_TIMESERIES: h/bound-1 salinity/bound-1, temperature/bound-1) (Despite the fact that the "tim" format is used more widely than just FLOW, there are some specifics involved.)
FLOW_MAPSTACK	Placeholder for the name of the file that will hold the scalar field data (as found in the map stack files). It should be followed by the name of the parameter: $(FLOW_MAPSTACK: pressure) Then: The string "FLOW_MAPSTACK pressure" is replaced by "pressure.dat" The file "pressure.dat" contains the map stacks in the format proper to Delft3D-FLOW The XML-file "map_pressure.xml" in the input directory contains the details: which ASCII files and so on.
WAVE_TIMEFRAME	Placeholder to fill values for TimePoint from start time to end time with specified increment. Example: $(WAVE_TIMEFRAME: 60, USE_WATERLEVEL_FLOW, USE_CURRENTS_FLOW) TimeStep in this case is 60 (optional): USE_WATERLEVEL_FLOW: use water levels from (offline) FLOW simulation (optional): USE_CURRENTS_FLOW: use current information from (offline) FLOW simulation
WAQ_TIME_START	Start of the simulation (format in accordance with Delft3D-WAQ/ECO: yyyy/mm/dd-hh:mm:ss)
WAQ_TIME_STOP	Stop of the simulation (format in accordance with Delft3D-WAQ/ECO: yyyy/mm/dd-hh:mm:ss)
WAQ_TIMESERIES	Placeholder to fill in the timeseries in the WAQ /ECO format (only the time and data, not the header). The keyword should be followed by the names of all timeseries that should be filled in there, separated by spaces: $(WAQ_TIMESERIES: salinity/bound-1, temperature/bound-1)
WAQ_MAPSTACK	Placeholder for the name of the file that will hold the scalar field data (as found in the map stack files). It should be followed by the name of the parameter: $(WAQ_MAPSTACK: windvel) Then: The string "WAQ_MAPSTACK windvel" is replaced by "windvel.dat" The file "windvel.dat" contains the map stacks in the format proper to Delft3D-WAQ/ECO The XML-file "map_windvel.xml" in the input directory contains the details: which ASCII files and so on.
PART_RUNID	The run ID for the Delft3D-PART computation (used in the filename.dat file)
PART_TIME_START	Placeholder to fill in start time in PART format, similar to WAQ and FLOW keywords. NOTE. PART requires the formating of the inp file to be very specific (incl. specific numbers of spaces/tabs before keywords.) Make sure your model runs before you start changing properties. Also, all text following the keyword will be replace/removed by the adapter when substituting the keyword
PART_TIME_STOP	Placeholder to fill in end time in PART format, similar to WAQ and FLOW keywords. NOTE. PART requires the formating of the inp file to be very specific (incl. specific numbers of spaces/tabs before keywords.) Make sure your model runs before you start changing properties. Also, all text following the keyword will be replace/removed by the adapter when substituting the keyword
PART_TIMESERIES	Placeholder to fill in the timeseries in the PART format, similar to the WAQ and FLOW timeseries keywords. NOTE. This only works in the .inp file. Not in an .inc file *NOTE. this requires the number of timesteps to be added to the .inp as well, see PART_NUMBER_BREAKPOINTS**
PART_NUMBER_BREAKPOINTS	Placeholder to fill in the number of time steps required for the wind input in the *.inp file. Example usage: ; Wind_parameters $(PART_NUMBER_BREAKPOINTS: Wind.speed/Spill_Location) ; dd hh mm ss speed(m/s) direction(degr.) $(PART_TIMESERIES: Wind.speed/Spill_Location, Wind.dir/Spill_Location)
PART_MAPSTACK	Placeholder to fill in mapstacks in the PART format. Example: ^(PART_MAPSTACK: x_wind,m s-1)
PART_INIFILE	File name for the initial patch - the header information is to be written by Delft-FEWS. Example: ^(PART_INIFILE: patch.ini)
PART_SHAPEFILE	File name for the shape file holding the polygon within which the particles will be released. Example: ^(PART_SHAPEFILE: patch.shp) Use in combination with the keyword "PART_INIFILE". The coordinates will be appended to the ini-file as written by FEWS.
TEKAL_FILE	Additional keyword for PART. Example: ^(TEKAL_FILE: dispers.pol)
TEKAL_VALUES	Additional keyword for PART. Example: ^(TEKAL_VALUES: lon.cleaned/obs1, lat.cleaned/obs1)
COUP_TIME_START	Start time of coupling (in seconds; time frame is that of Delft3D-FLOW)
COUP_TIME_STOP	Stop time of coupling (in seconds; ditto)
P.M.	Keywords specific to Delft3D-WAVE

For examples, see the MDF, MDW, BCC, WND, BND and INP files attached to this WiKi page.

4. Configuration examples

4.1 Running model adapter and Delft3D from Delft-FEWS

The Delft3D model adapter and executable can be executed from Delft-FEWS in the following way:

 <executeActivities>
    <executeActivity>
       <description>Delft3D Adapter</description>
       <command>
          <className>nl.wldelft.fews.adapter.delft3d.Delft3DPreAdapter</className>
       </command>
       <arguments>
          <argument>%ROOT_DIR%</argument>
          <argument><adapter configuration file></argument>
       </arguments>
       <timeOut>10800000</timeOut>
       <overrulingDiagnosticFile>%ROOT_DIR%\diagnostics\delft3dpreadapter.xml</overrulingDiagnosticFile>
    </executeActivity>
    <executeActivity>
       <description>Run delftflow</description>
       <command>
          <executable>bin/deltares_hydro.exe</executable>
       </command>
       <arguments>
          <argument>config-flow2d3d.ini</argument>
       </arguments>
       <timeOut>90000000</timeOut>
       <overrulingDiagnosticFile>%ROOT_DIR%/dcsmv5_Diagnostic_Placeholder.xml</overrulingDiagnosticFile>
    </executeActivity>
    <executeActivity>
       <description>Delft3D Adapter</description>
       <command>
          <className>nl.wldelft.fews.adapter.delft3d.Delft3DPostAdapter</className>
       </command>
       <arguments>
          <argument>%ROOT_DIR%</argument>
          <argument><adapter configuration file></argument>
       </arguments>
       <timeOut>10800000</timeOut>
       <overrulingDiagnosticFile>%ROOT_DIR%\diagnostics\delft3dpostadapter.xml</overrulingDiagnosticFile>
    </executeActivity>
</executeActivities>

The Delft3D model executable can be called directly (as shown in the above example), of by calling an external batch file to execute the model.

For examples, see the generalAdapter_example_*.xml files attached to this WiKi page.

4.2 Cold and Warm State management

Delft-FEWS required to have a cold state file for each Delft3D model in the ColdStates folder (zipped). This cold state file is a Delft3D restart file which needs to be generated by the model developer up-front (outside of Delft-FEWS), and needs to describe representative initial conditions.

The below configuration shows an example of the exportStateActivity to export a Delft3D model state from the Delft-FEWS generalAdapter.

<exportStateActivity>
   <moduleInstanceId>DCSM_Historical</moduleInstanceId>
   <stateExportDir>%ROOT_DIR%/stateInput</stateExportDir>
   <stateConfigFile>%ROOT_DIR%/stateInput/export_states.xml</stateConfigFile>
   <stateLocations type="file">
      <stateLocation>
         <readLocation>dcsm98.res</readLocation>
         <writeLocation>dcsm98.res</writeLocation>
      </stateLocation>
   </stateLocations>
   <stateSelection>
      <warmState>
         <stateSearchPeriod unit="hour" start="-48" end="-1"/>
      </warmState>
   </stateSelection>
</exportStateActivity>

From the Delft3D-FLOW file this initial state file is subsequently called in the following way:

Commnt=
Restid= #dcsm98.rst#
Commnt=

The warmState search period should be sufficiently long to spin-up the model in case of a cold start.

4.3 Import and display 3D data (z layers)

First create a location for each z layer, all linked to the same parentLocation for the grid.

Locations.xml

    <location id="Delft3D.grid.L1" name="Delft3D.grid.L1">	
        <description>Delft3D.grid.L1</description>
        <parentLocationId>Delft3D.grid</parentLocationId>	<!-- all z layers are linked to the same parentLocation -->
        <x>0</x>
        <y>0</y>
        <z>-30.5</z>
    </location>
    <location id="Delft3D.grid.L2" name="Delft3D.grid.L2">
        <description>Delft3D.grid.L2</description>
        <parentLocationId>Delft3D.grid</parentLocationId>	<!-- all z layers are linked to the same parentLocation -->
        <x>0</x>
        <y>0</y>
        <z>-29.5</z>
    </location>
	... 												 	<!-- repeat for all layers -->

Grid linked to these locations is defined in Grids.xml

Grids.xml

    <irregular locationId="Delft3D.grid.L1">
        <rows>103</rows>
        <columns>209</columns>
        <csvFile>
            <file>Delft3D_grid.csv</file>
            <geoDatum>UTM17N</geoDatum>
            <x>%X%</x>
            <y>%Y%</y>
            <z>-30.5</z>
        </csvFile>
    </irregular>
    <irregular locationId="Delft3D.grid.L2">
        <rows>103</rows>
        <columns>209</columns>
        <csvFile>
            <file>Delft3D_grid.csv</file>
            <geoDatum>UTM17N</geoDatum>
            <x>%X%</x>
            <y>%Y%</y>
            <z>-29.5</z>
        </csvFile>
    </irregular>
	... 												 	<!-- repeat for all layers -->

Import the 3D data after the model run in the generalAdapter

generalAdapter - import 3D data from model with z layers

        <importActivities>
			<importMapStacksActivity>
                <importFile>S.simulated.L1.xml</importFile>
                <timeSeriesSets>
                    <timeSeriesSet>
                        <moduleInstanceId>Delft3D_FC</moduleInstanceId>
                        <valueType>grid</valueType>
                        <parameterId>S.simulated</parameterId>
                        <locationId>Delft3D.grid.L1</locationId>
                        <timeSeriesType>simulated forecasting</timeSeriesType>
                        <timeStep unit="nonequidistant"/>
                        <readWriteMode>add originals</readWriteMode>
                        <synchLevel>2</synchLevel>
                        <expiryTime unit="day" multiplier="2"/>
                    </timeSeriesSet>
                </timeSeriesSets>
            </importMapStacksActivity>
            <importMapStacksActivity>
                <importFile>S.simulated.L2.xml</importFile>
                <timeSeriesSets>
                    <timeSeriesSet>
                        <moduleInstanceId>Delft3D_FC</moduleInstanceId>
                        <valueType>grid</valueType>
                        <parameterId>S.simulated</parameterId>
                        <locationId>Delft3D.grid.L2</locationId>
                        <timeSeriesType>simulated forecasting</timeSeriesType>
                        <timeStep unit="nonequidistant"/>
                        <readWriteMode>add originals</readWriteMode>
                        <synchLevel>2</synchLevel>
                        <expiryTime unit="day" multiplier="2"/>
                    </timeSeriesSet>
                </timeSeriesSets>
            </importMapStacksActivity>
			.... 																	<!-- repeat for all layers -->
		</importActivities>

Display the 3D data in the gridDisplay

generalAdapter - import 3D data from model with z layers

        <gridPlotGroup>
		 	.... 																	<!-- create gridPlot for each z layer -->
            <gridPlot id="L2">
				<dataLayer>
                    <timeSeriesSet>
                        <moduleInstanceId>Delft3D_FC</moduleInstanceId>
                        <valueType>grid</valueType>
                        <parameterId>S.simulated</parameterId>
                        <locationId>Delft3D.grid.L2</locationId>
                        <timeSeriesType>simulated forecasting</timeSeriesType>
                        <timeStep unit="nonequidistant"/>
                        <relativeViewPeriod unit="day" startOverrulable="true" start="-3" end="2"/>
                        <readWriteMode>read complete forecast</readWriteMode>
                    </timeSeriesSet>
                </dataLayer>
            </gridPlot>
            <gridPlot id="Bed">
                <dataLayer>
                    <timeSeriesSet>
                        <moduleInstanceId>Delft3D_FC</moduleInstanceId>
                        <valueType>grid</valueType>
                        <parameterId>S.simulated</parameterId>
                        <locationId>Delft3D.grid.L1</locationId>
                        <timeSeriesType>simulated forecasting</timeSeriesType>
                        <timeStep unit="nonequidistant"/>
                        <relativeViewPeriod unit="day" startOverrulable="true" start="-3" end="2"/>
                        <readWriteMode>read complete forecast</readWriteMode>
                    </timeSeriesSet>
                </dataLayer>
            </gridPlot>
        </gridPlotGroup>

5. 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.

6. How-to's

6.1 Grid definition Delft3D in Delft-FEWS

To import gridded output from Delft3D into Delft-FEWS, a grid definition needs to be specified in the Delft-FEWS grids.xml file. This grid file can be generated using the Matlab script print_Delft3D_grid.m attached to this WiKi. For WAQ models coupled over complex domains, the grid information generated by Delft3D is often not easily read in Delft-FEWS. The ccotoldbn tool can be used in this case to convert the *.lga and *.cco file from a WAQ model into a shape file. Examples and documentation are attached to this wiki page below. ccotoldbn.exe ccotoldbn-readme.txt

	File	Modified
	XML File adapterConfiguration_example_flow.xml Example model adapter configuration file for Delft3D-FLOW	28-03-2013 by Daniel Twigt
	Labels No labels Preview
	XML File adapterConfiguration_example_waq.xml Example model adapter configuration file for Delft3D-WAQ	28-03-2013 by Daniel Twigt
	Labels No labels Preview
	XML File adapterConfiguration_example_wave.xml Example model adapter configuration file for Delft3D-WAVE	28-03-2013 by Daniel Twigt
	Labels No labels Preview
	File ccotoldbn.exe	18-12-2017 by Lora Buckman
	Labels No labels Preview
	Text File ccotoldbn-readme.txt	18-12-2017 by Lora Buckman
	Labels No labels Preview
	File example_flow.bcc Example BCC file Delft3D-FLOW with placeholder keywords	28-03-2013 by Daniel Twigt
	Labels No labels Preview
	File example_flow.mdf Example MDF file Delft3D-FLOW with placeholder keywords	28-03-2013 by Daniel Twigt
	Labels No labels Preview
	File example_flow.wnd Example WND file Delft3D-FLOW with placeholder keywords	28-03-2013 by Daniel Twigt
	Labels No labels Preview
	File example_waq.inp Example INP file Delft3D-WAQ with placeholder keywords	28-03-2013 by Daniel Twigt
	Labels No labels Preview
	File example_wave.bnd Example BND file Delft3D-WAVE with placeholder keywords	28-03-2013 by Daniel Twigt
	Labels No labels Preview
	File example_wave.mdw Example MDW file Delft3D-WAVE with placeholder keywords	28-03-2013 by Daniel Twigt
	Labels No labels Preview
	XML File generalAdapter_example_flow.xml Example generalAdapter configuration file for Delft3D-FLOW	28-03-2013 by Daniel Twigt
	Labels No labels Preview
	Text File print_Delft3D_grid.m Example Matlab script to generate grids.xml file for Delft3D grid in FEWS	28-03-2013 by Daniel Twigt
	Labels No labels Preview

Download All

Page tree

Delft3D adapter

1. Directory structure

2. Configuration file

2.1 Section: <general>

2.2 Section: <preAdapter>

2.3 Section: <postAdapter>

Command-line option -swapNorthSouth

Command-line option -skipFirstTimeStep

Export types

Delft3D-FLOW (example):

Delft3D-WAQ (example):

Delft3D-WAVE (example):

Delft3D-PART (example):

3. Template files and keywords

4. Configuration examples

4.1 Running model adapter and Delft3D from Delft-FEWS

4.2 Cold and Warm State management

4.3 Import and display 3D data (z layers)

5. Configuration errors

6. How-to's

6.1 Grid definition Delft3D in Delft-FEWS