View Source

Description and examples of adapter configuration to use a Sobek-3 (DeltaShell) model in FEWS.

Function:	Functionality to use FewsAdapter of DeltaShell and how to use them in your configuration
Where to Use?	General Adapter
Why to Use?	To be able to run a Sobek-3 model
Description:	Description and examples of adapter configuration to use a Sobek-3 (DeltaShell) model in FEWS.
Available since:	Delft-FEWS 201201

General

Installation requirements

It is not required to have DeltaShell SOBEK installed at the PC as it is possible to embed the DeltaShell Adapter binaries of SOBEK in to the FEWS configuration. There is a special build available (FEWS_Adapter.zip) that can be simple unzipped in the FEWS Modules directory, e.g. <Region>\Modules\Sobek3\bin, where the DeltaShell.FewsAdapter.exe is located.

There should a valid license to use Sobek-3, preferably including Terminal Server license (TS_OK).

Interaction between FEWS and Sobek

The adapter does not have any seperate configuration. All options and definitions are parsed through the General Adapter's PI-Run file. The desired output is completely defined in FEWS only and parsed to SOBEK.

Available time series

H boundary
Q boundary
lateral timeseries
wind speed and direction
concentration or Masses on bounds en lateral (e.g. Salinity, conc. and mass)
RTC Setpoint (interval, PID)
struc crest level
struc crest width
struc gate level
struc pump capacity
rainfall
evaporation

Delft-FEWS Configuration

Definition of Sobek locations from Shape files

General

SOBEK-3 has an option to export the model network to shape files, which can be easily imported into FEWS as locations. Sobek exports a seperate file for node and line objects, e.g.

fews_ds_<model name>line_data_items.shp and fews_ds<model name>_node_data_items.shp
This is a ArcGIS shape file that contains all the line and node objects in the model
fews_ds_<model name>_model_data_data_items.csv
Contains all objects that can get time series data as input, or have simulation output. Columns are: ParameterType,LocationName,UserInterfaceName,ParameterId,LocationId,LocationType,X,Y
profile_definition_<route id>grid_points.xml and profile_definition<route id>_reach_segments.xml
A set of two files (gridpoints and reachsegments) per longitudinal profile (route) as defined in the model. The file format is FEWS PI xml

..\bin\DeltaShell.FewsAdapter.exe -all         <dsproj file> <model name>
..\bin\DeltaShell.FewsAdapter.exe -dbf        <dsproj file> <model name>
..\bin\DeltaShell.FewsAdapter.exe -csv       <dsproj file> <model name>
..\bin\DeltaShell.FewsAdapter.exe -profiles <dsproj file> <model name>

Nodes and Reach segments

The shape files have the TYPE property in the associated DBF file. The possible types are (case sensitive):

HBoundary
QBoundary
ObservationPoint
Weir
Pump
Bridge
Culvert
LateralSource
grid_point
reach_segment

Example configuration in LocationSets.xml:

<locationSet id="DS_LWMl">
  <esriShapeFile>
    <file>fews_ds_Lauwersmeermodel_line_data_items</file>
    <geoDatum>Rijks Driehoekstelsel</geoDatum>
    <charset>Cp850</charset>
    <id>DS_LWM_%ID%</id>
    <name>%ID% - %NAME%</name>
    <description>Deltashell sobek3 testmodel</description>
    <x>%X_CENTRE%</x>
    <y>%Y_CENTRE%</y>
    <attribute id="SOBEK_ID">
      <text>%ID%</text>
    </attribute>
    <attribute id="SOBEK_PARENTID">
      <text>%TYPE%</text>
    </attribute>
    <attribute id="SOBEK_MODEL">
      <text>LWM</text>
    </attribute>
  </esriShapeFile>
</locationSet>
<locationSet id="DS_LWMn">
  <esriShapeFile>
    <file>fews_ds_Lauwersmeermodel_node_data_items</file>
    <geoDatum>Rijks Driehoekstelsel</geoDatum>
    <charset>Cp850</charset>
    <id>DS_LWM_%ID%</id>
    <name>%ID% - %NAME%</name>
    <description>Deltashell sobek3 testmodel</description>
    <x>%X%</x>
    <y>%Y%</y>
    <attribute id="SOBEK_ID">
      <text>%ID%</text>
    </attribute>
    <attribute id="SOBEK_PARENTID">
      <text>%TYPE%</text>
    </attribute>
    <attribute id="SOBEK_MODEL">
      <text>LWM</text>
    </attribute>
  </esriShapeFile>
</locationSet>
<locationSet id="DS_LWM_Qbnd">
  <locationSetId>DS_LWMn</locationSetId>
  <constraints>
    <attributeTextEquals id="SOBEK_PARENTID" equals="QBoundary"/>
  </constraints>
</locationSet>
<locationSet id="DS_LWM_waterlevel_nodes">
  <locationSetId>DS_LWMn</locationSetId>
  <constraints>
    <anyValid>
      <attributeTextEquals id="SOBEK_PARENTID" equals="grid_point"/>
      <attributeTextEquals id="SOBEK_PARENTID" equals="HBoundary"/>
      <attributeTextEquals id="SOBEK_PARENTID" equals="QBoundary"/>
    </anyValid>
  </constraints>
</locationSet>
<locationSet id="DS_LWM_structures">
  <locationSetId>DS_LWMn</locationSetId>
  <constraints>
    <anyValid>
      <attributeTextEquals id="SOBEK_PARENTID" equals="Weir"/>
      <attributeTextEquals id="SOBEK_PARENTID" equals="Pump"/>
      <attributeTextEquals id="SOBEK_PARENTID" equals="Bridge"/>
      <attributeTextEquals id="SOBEK_PARENTID" equals="Culvert"/>
    </anyValid>
  </constraints>
</locationSet>

Model data items

It is possible to create a CSV file that contains all relevant information.
Columns are:

ParameterType: Input or Output
LocationName: name in sobek of the object
UserInterfaceName: name of outputparameter in the user interface
ParameterId: ID that should be used in the adapter (NetCDF compliant ID)
LocationId: ID of the location
LocationType: like wind, LaterSource etc (see TYPE column in SHP/DBF)
X: X-coordinate in local geoDatum of the sobek model
Y: Y-coordinate in local geoDatum of the sobek model

..\bin\DeltaShell.FewsAdapter.exe -csv <dsproj file> <model name>

Longitudinal profiles (routes)

It is possible to define longitudinal profiles in SOBEK which can also be directly exported to a FEWS branch definition. The simulation results can also be directly derived from SOBEK. The routes can be generated by the command

..\bin\DeltaShell.FewsAdapter.exe \-profiles <dsproj file> <model name>

The output is a set of two files (gridpoints and reachsegments) per longitudinal profile (route) as defined in the model. The file format is FEWS PI xml. See the XSD or the FEWS Wiki.

Maps

will be available for 2D only, which is currently still not in SOBEK-3

General Adapter

The Delft-FEWS General Adapter starts the FEWS-DeltaShell adapter and provides all relevant information to the DeltaShell Adapter.
Configuration options are parsed to the Adapter through the so-called PI run file. In this file also references to input and output files are listed.

PI run file

All possible options are defined the PI run file that FEWS provides to the Adapter. The options are:

option	description	required	default	example
deltaShellProjectFile	..	yes	-	%ROOT_DIR%\DSModel\lauwersmeer.dsproj
model	..	yes	-	Lauwersmeermodel
piTimeSeriesAsBin	option to write output to binairy PI files to allow for better performance on large output time series	no	false	true
saveResultsInCopyOfProject	This option is available for debug purpose. It saves always a copy of the simulation to "Copy of <project>"	no	false	true
workDir	<model name>	Directory where to run the simulation of this model	no	%TEMP% directory	%ROOT_DIR%/Work

Example of PI Run configuration

<exportRunFileActivity>
  <exportFile>pi-run.xml</exportFile>
  <properties>
    <string key="deltaShellProjectFile" value="%ROOT_DIR%\DSModel\lauwersmeer.dsproj"/>
    <string key="model" value="Lauwersmeermodel"/>
    <string key="piTimeSeriesAsBin" value="true"/>
    <string key="saveResultsInCopyOfProject" value="true"/>
    <string key="workDir|Lauwersmeermodel" value="%ROOT_DIR%/Work"/>
  </properties>
</exportRunFileActivity>

Id Maps

Sobek expects the parameters to be in NetCDF standard IDs.

item in model	Sobek parameter id	Sobek module
H boundary	water_level	1D flow
Q boundary	water_discharge	1D flow
laterals	water_discharge	1D flow
wind speed	wind_speed	1D flow
wind direction	wind_direction	1D flow

to do:

concentration or Masses on bounds en lateral (e.g. Salinity, conc. and mass)
RTC Setpoint (interval, PID)
struc crest level
struc crest width
struc gate level
struc pump capacity
rainfall
evaporation

Unit Conversion

DeltaShell uses the NetCDF standard units for each parameter. That may require a unit conversion.

<unitConversions 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/unitConversions.xsd">
	<unitConversion>
		<inputUnitType>m</inputUnitType>
		<outputUnitType>m AD</outputUnitType>
		<multiplier>1</multiplier>
		<incrementer>0</incrementer>
	</unitConversion>
	<unitConversion>
		<inputUnitType>graden</inputUnitType>
		<outputUnitType>deg</outputUnitType>
		<multiplier>1</multiplier>
		<incrementer>0</incrementer>
	</unitConversion>
</unitConversions>

Time Series Input files to Sobek

The DeltaShell Adapter only accepts scalar time series in PI format. ParameterIDs should be according to the NetCDF standard, so many times an IdMap is required (see below). The locationIDs should correspond with objects in the models.

At the moment DeltaShell has no clear handling of ID's, names and descriptions of objects. They are handled differently over the various plugins (1D-Flow, RTC, WQ or RR). Be aware of this when you configure the idMappings.....

TimeSeries Outputfiles from Sobek

Two types of output files are supported: the PI scalar and the PI profile time series files.
Both should be exported before the simulation starts with the option exportPlaceholderFile=true. The DeltaShell adapter derives the expected output from the headers in these files. It is possible to spread the wanted output time series over various files.

The output parameters should again fit the NetCDF parameters:

Output on ..	Parameter	NetCDF parameter ID
Structure	Crest level (s)	structure_crest_level
Structure	Crest width (s)	structure_crest_width
Structure	Discharge (s)	water_discharge
Structure	Flow area (s)	water_flow_area
Structure	Gate lower edge level (s)	structure_gate_lower_edge_level
Structure	Head Difference (s)	at_structure_water_head
Structure	Opening height (s)	structure_gate_opening_height
Structure	Pressure difference (s)	at_structure_water_pressure_difference
Structure	Valve opening (s)	structure_valve_opening
Structure	Velocity (s)	water_velocity
Structure	Water level at crest (s)	at_crest_of_structure_water_level
Structure	Water level down (s)	at_structure_downstream_water_level
Structure	Water level up (s)	at_structure_upstream_water_level
LateralSource	Discharge (l)	water_discharge
LateralSource	Water level (l)	water_level
ObservationPoint	Discharge (op)	water_discharge
ObservationPoint	Velocity (op)	water_velocity
ObservationPoint	Water depth (op)	water_depth
ObservationPoint	Water level (op)	water_level
grid_point	Negative depth	nonstandard_negative_depth
grid_point	Number of iterations	nonstandard_no_iteration
grid_point	Salt concentration	water_salinity
grid_point	Total area	nonstandard_total_area
grid_point	Total width	nonstandard_water_width
grid_point	Water depth	water_depth
grid_point	Water level	water_level
grid_point	Water volume	water_volume
reach_segment	Conveyance	water_conveyance
reach_segment	Discharge	water_discharge
reach_segment	Flow area	water_flow_area
reach_segment	Froude number	froude_number
reach_segment	Time step estimation	nonstandard_timestep_estimation
reach_segment	Velocity	water_velocity
reach_segment	Water level gradient	water_level_gradient
..	..	..
..	..	..

Default the output is the current output at the output timestep. It is possible to get actual, average or maximum values by using a qualifier.
The possible qualifiers are:

Output values	Qualifier ID
average	average
maximum	max
actual values	current

State files

DeltaShell supports state files (or restart files). It is possible to use state files as initial condition and to store the last state of the simulation as state. The state files should be provided all

1D-Flow: sobek.rda, sobek.rdf

RTC, RR, WQ to be added

<exportStateActivity>
  <moduleInstanceId>DS_LWM_Historie</moduleInstanceId>
  <stateExportDir>%ROOT_DIR%/States</stateExportDir>
  <stateConfigFile>%ROOT_DIR%/States/Inputstates.xml</stateConfigFile>
  <stateLocations type="file">
    <stateLocation>
      <readLocation>restart_files_in.zip</readLocation>
      <writeLocation>restart_files_out.zip</writeLocation>
    </stateLocation>
  </stateLocations>
  <stateSelection>
    <warmState>
      <stateSearchPeriod unit="hour" start="-96" end="-2"/>
    </warmState>
  </stateSelection>
</exportStateActivity>

todo: how to get the restart files?

Diagnostics

todo

Possible messages

<Diag xmlns="http://www.wldelft.nl/fews/PI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.2">
    <line level="3" description="wo 13-06-2012 07:43:39 Started FewsAdapter, runinfo from
D:\FEWS201201\DeltaShell\Modules\DS\Jakarta\./Input/pi-run.xml diagnostics into
D:\FEWS201201\DeltaShell\Modules\DS\Jakarta\Logs\diagnostics.xml"/>
    <line level="3" description="wo 13-06-2012 07:44:28 Model flow model 1d execute start"/>
    <line level="3" description="wo 13-06-2012 07:46:50 Provide output time series values."/>
    <line level="3" description="wo 13-06-2012 07:47:19 Fews Adapter Run completed, date: 06/13/2012 07:47:19"/>
</Diag>

Miscellaneous

todo

Performance

todo

How to run ensembles

todo

Contents

General

Installation requirements

Interaction between FEWS and Sobek

Available time series

Delft-FEWS Configuration

Definition of Sobek locations from Shape files

General

Nodes and Reach segments

Model data items

Longitudinal profiles (routes)

Maps

General Adapter

PI run file

Id Maps

Unit Conversion

Time Series Input files to Sobek

TimeSeries Outputfiles from Sobek

State files

Diagnostics

Miscellaneous

Performance

How to run ensembles