The Delft3D-FEWS model adapter applies an XML configuration file in order to group configuration dependant settings in a practical way. This XML file has an associated XSD scheme which defines the XML file format in a structured way. This XML/XSD approach is used for all configurable FEWS files.
During Delft3D-FEWS configuration, the user is required to configure the contents of the model adapter XML file for that particular Delft3D-FEWS setup. While this XML file is ASCII based and can be edited using a standard text editor, the user is advised to use specific XML editors, like XMLSpy, to do this. This way, the user can benefit from the structured file contents as defined in the XSD scheme.
In this section, the contents of the Delft3D-FEWS model adapter XML scheme is described and the user is explained on how to edit this file for particular Delft3D-FEWS setups. While this is also briefly discussed in the section Configuration workflow, this section provides more details on the various settings in this file.
For this manual, we will assume that the XML configuration file is named Delft3Dmodel.xml (in accordance with the XSD scheme). During configuration, however, the user is free to rename this file is required.
XML configuration file
As outlined above, the Delft3D-FEWS model adapter applies an XML configuration file in order to group configuration dependant settings in a practical way. More precisely, this configuration file is used to define model adapter settings not supported by the FEWS General Adapter module (or settings requiring additional flexibility). During setup of this file, the goal was to prevent duplicate information in the model adapter XML configution file and the general adapter module, thus preventing possible conflicts and errors in the system configuration. As such, available settings in the model adapter XML configution are limited to those strictly required by the system.
Figure 1 below shows the XSD scheme for the Delft3D-FEWS model adapter XML configuration file. In the below text, the sections <general>, <preAdapter> and <postAdapter> are explained in more detail.
PLACEHOLDER FIGURE XSD SCHEME
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 Table 1 below). With these four keywords the user should be able to define the characteristics of most runs of Delft3D modules. For some particular cases, for example when running Delft3D-FLOW with RTC, additional input arguments are required to executate the model. These arguments should be provided as additional input arguments when executing the model adapter from the general adapter module. For more information, see section Configuration workflow.
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. See also section Configuration workflow about the relation between these directories and the overall directory structure of a Delft3D-FEWS application.
Keyword | Settings |
|---|---|
<description | Optional description of file contents |
<module> | FLOW, WAQ, ECO, PART or WAVE |
<runId> | RunId of template input files (<runId>.mdf, <runId.inp> or <runid.mdw> |
<workDir> | Working folder in which simulation is run |
<modelDir> | Repository directory of static model data and templates |
Table 1: Configurable settings in <general> section of XML configuration file Delft3D-FEWS adapter.
Section <preAdapter>
The <preAdapter> section contains one keyword only, <steeringTimeSeriesName>, the name of the timeseries that is to be used as to determine the time frame of the simulation (found in the timeseries exported by Delft-FEWS).
The reason for this keyword is that Delft-FEWS determines the actual modelling timeframe based on user defined start and stop times in the general adapter module and on the availability of state information within this timeframe. Because of the latter, the start time of a model simulation is not necessarily fixed but may vary based on the available of this state information (see also section State handling). The Delft3D model should be able to cope with this by changing the simulation period accordingly. To achieve this, the model adapter will assess the user specified <steeringTimeSeriesName> and will base its simulation period (starttime and stoptime) on the duration of this timeseries.
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'. See also the section on Naming conventions.
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. This is preferable given the (possibly) significant file size of Delft3D output files.
To achieve this, the <postAdapter> section contains a mapping table relating Delft3D output to internal Delft-FEWS parameters and locations. Based on these mapping relations, the postAdapter will convert native model output to PI XML timeseries and mapStacks to be imported by FEWS during the <importActivities> of the general adapter module (see also section Configuration workflow).
Note that this mapping table works in a similar way as FEWS IdMaps, where external locations and parameters and internal locations and parameters are related to each other. Since the mapping table in this configuration file already links model output to the appropriate internal locations and parameters in FEWS no specific IdMap is required in this case. To this end it is essential that these locations and parameters exist in the given FEWS application, however.
The external locations and parameters as described in this mapping table are derived from the parameter names and the location names as seen in Delft3D-GPP (the adapter uses the same library as Delft3D-GPP to read the model output files). This implies that the external locations and parameters should be set based on naming conventions which are outlined in section Naming conventions.