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