Page History

...

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 . This model adapter presently 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.

...

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)

...

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

...

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:

...

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

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 FEWS

To import gridded output from Delft3D into FEWS, a grid definition needs to be specified in the 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 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

6.2 State management

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 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 FEWS generalAdapter.

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.

Code Block

	xml
	xml

<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:

Code Block
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.

Code Block

title	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">

Code Block

xml

<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><description>Delft3D.grid.L2</description>
      </stateLocation>
  <parentLocationId>Delft3D.grid</parentLocationId>	<!-- all z layers are linked to the same parentLocation -->
        <<x>0</stateLocations>x>
   <stateSelection>
     <y>0</y>
        <z>-29.5</z>
   <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:

Code Block
Commnt= Restid= #dcsm98.rst# Commnt=

 </location>
	... 												 	<!-- repeat for all layers -->

Grid linked to these locations is defined in Grids.xml

Code Block

title	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

Code Block

title	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

Code Block

title	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

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

Attachments

Page tree

Versions Compared

Old Version 55

New Version 56

Key

Command-line option -swapNorthSouth

4. Configuration examples

4.1 Running model adapter and Delft3D from Delft-FEWS

5. Configuration errors

6. How-to's

6.1 Grid definition Delft3D in FEWS

6.2 State management

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