1 JFlow
JFlow is a two-dimensional hydraulic model, which solves the St Venant Shallow Water Equations. It makes use of GPU technology to complete simulations faster and more efficiently.
The model is designed to simulate the movement of water over floodplains, rather than in-bank river flows, and it provides predictions of water depths, velocity and hazard.
JFlow and its adapter are developed and maintained by JBA Consulting. Further details can be found at www.jflow.co.uk.
2 General Adapter
2.1 Overview
The general adapter:
- Populates the JFlow model with either flow or rainfall data exported from FEWS
- Triggers the JFlow executable
- Processes model results (ASCII grids) for import into FEWS
General notes:
- The adapter is a standalone executable and no installation is required.
- The adapter assumes that the JFlow model sits within a specific module folder structure - further details are given in Section 2.2.
- An .ini file provides the adapter with model-specific information - Section 2.3 contains full details.
- Notes about how FEWS should be configured are given in Section 2.4.
2.2 Module folder structure
The model folder should sit within 'FEWS_SA/modules/jflow/' where 'FEWS_SA' is the root of the standalone.
Each model folder contains the following sub-folders:
- Input - will be populated with xml timeseries data from FEWS. Inputs to JFlow can be either rain or flow.
- Model - contains the JFlow model files.
- Output - will be populated with results from JFlow.
2.3 jflow.ini file
The adapter is driven by an .ini file, which sits within the root of the model folder. Its purpose is to list model-specific information, such as inflow boundaries and model outputs.
The JFlow adapter expects the file to be called jflow.ini. Currently, the .ini file must be created manually. The table below summarises its contents.
Parameter | Description | Type |
JflowExecutable | Full filepath of the JFlow executable, as installed on the host machine. | String |
JflowDB | Name of the JFlow database, including file extension. The full filepath is not required if the module folder structure is maintained. | String |
Device | Number of the GPU device, as machines may have multiple GPU cards. Default is 0. | Integer |
NumberFlowIDs | Number of flow boundaries. | Integer |
FlowNames | Names of flow boundaries, separated by commas. The name should match (1) the inflow ID in the JFlow model; and, (2) the external location ID of the xml timeseries exported from FEWS. Any ID mapping takes place within FEWS. | String |
NumberRainIDs | Number of rainfall inputs. | Integer |
RainNames | Names of the rainfall inputs, separated by commas. The name should match (1) the inflow ID in the JFlow model; and, (2) the external location ID of the xml timeseries exported from FEWS. Any ID mapping takes place within FEWS. | String |
OutputParameters | Output parameter types, separated by commas. Commonly used options are: depth, hazard_index, velocity, water_level. | String |
LocationID | LocationID that will be associated with the model results. The value stated here should match the external ID in the FEWS ID mapping file. | String |
Example .ini file:
[General] ModelName=Jflow_test_model JflowExecutable=C:\Program Files\JFLOW\JFLOW.exe JflowDB=jflow_test.accdb Device=0 [End] [Flow inputs] NumberFlowIDs=3 FlowNames=Flow_1, Flow_2, Flow_3 [End] [Rain inputs] NumberRainIDs=0 RainNames=0 [End] [Required outputs] OutputParameters=depth LocationID=Jflow_test_map [End]
2.4 Notes on configuration
2.4.1 Module config file examples
The following sections contain examples of a module configuration file required to run JFlow through the JFlow adapter. Notes for users are also given.
<?xml version="1.0" encoding="UTF-8"?>
<generalAdapterRun 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/generalAdapterRun.xsd">
<general>
<!-- general section to specify directories and id maps file -->
<description>JFlow fluvial test for the Don</description>
<rootDir>%REGION_HOME%/Modules/jflow/TestModel</rootDir>
<workDir>%ROOT_DIR%</workDir>
<exportDir>%ROOT_DIR%/input</exportDir>
<exportIdMap>Jflow_Export_Test</exportIdMap>
<importDir>%ROOT_DIR%/output</importDir>
<importIdMap>Jflow_Import_Test</importIdMap>
<dumpFileDir>$GA_DUMPFILEDIR$</dumpFileDir>
<dumpDir>%ROOT_DIR%</dumpDir>
<diagnosticFile>%ROOT_DIR%/diagnostics.xml</diagnosticFile>
</general>
<!-- burnInProfile - not currently used -->
<activities>
<startUpActivities>
<!-- startUpActivities to remove files from previous runs -->
<purgeActivity>
<filter>%ROOT_DIR%/input/*.*</filter>
</purgeActivity>
<!--purgeActivity>
<filter>%ROOT_DIR%/output/*.*</filter>
</purgeActivity-->
</startUpActivities>
Export time series from FEWS
The export file must be called export.xml (this is hard coded into the JFlow adapter).
<exportTimeSeriesActivity>
<description>Export flow timeseries</description>
<!-- exportFile is written to directory named in the General section unless specified otherwise-->
<exportFile>export.xml</exportFile>
<timeSeriesSets>
<timeSeriesSet>
<!-- the data to be exported -->
<moduleInstanceId>ImportObservedForJflow</moduleInstanceId>
<valueType>scalar</valueType>
<parameterId>Q.obs</parameterId>
<locationId>JBA_TEST1_SP_1</locationId>
<locationId>JBA_TEST1_SP_2</locationId>
<locationId>JBA_TEST1_SP_3</locationId>
<timeSeriesType>external historical</timeSeriesType>
<timeStep unit="minute" multiplier="15"/>
<relativeViewPeriod unit="hour" start="-24" end="0" endOverrulable="true"/>
<readWriteMode>read only</readWriteMode>
</timeSeriesSet>
</timeSeriesSets>
</exportTimeSeriesActivity>
Execute the JFlow model
<executeActivity>
<description>Run Jflow Adapter</description>
<command>
<!-- set path to Jflow adapter executable in the global properties file-->
<executable>$GA_JFLOW_ADAPTER$</executable>
</command>
<arguments>
<argument>%ROOT_DIR%\jflow.ini</argument>
</arguments>
<timeOut>900000</timeOut>
</executeActivity>
Import model results to FEWS
Import the model results grids to a location in FEWS, as in the example below.
JFlow results are written out as ASCII grids for each timestep. To relate each grid to a specific date and time, the JFlow adapter creates an XML file called jflowmapstacks.xml.
<locationID> should match the internal ID specified in the IdMaps file.
<importActivities>
<importMapStacksActivity>
<importFile>../output/jflowmapstacks.xml</importFile>
<timeSeriesSets>
<timeSeriesSet>
<moduleInstanceId>Jflow_test_Historical</moduleInstanceId>
<valueType>grid</valueType>
<parameterId>H.simulated.historical</parameterId>
<locationId>Jflow_test_map</locationId>
<timeSeriesType>simulated historical</timeSeriesType>
<timeStep unit="nonequidistant"/>
<readWriteMode>add originals</readWriteMode>
</timeSeriesSet>
</timeSeriesSets>
</importMapStacksActivity>
</importActivities>
2.4.2 Id maps
Export to JFlow from FEWS
External location IDs must match the JFlow flow or rain boundary names (as in the 'FlowNames' or 'RainNames' fields in the .ini file).
An internal and external parameter should also be specified (e.g. P.obs, Q.simulated etc.); this is required for FEWS to export the appropriate data series. However, the external parameter value is not used by the JFlow adapter itself - instead, the adapter works out the data type based on the .ini file (using the 'NumberFlowIDs' or 'NumberRainIDs' fields).
Import from JFlow to FEWS
External location IDs should match the LocationID specified in the.ini file. This is used to attribute model results with a location ID. Internal IDs should match the location configured in FEWS.
External parameter type (depth, hazard, velocity etc.) should match the value specified in the .ini file 'OutputParameters' field.
