Page tree
Skip to end of metadata
Go to start of metadata

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:

  1. Populates the JFlow model with either flow or rainfall data exported from FEWS
  2. Triggers the JFlow executable
  3. 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:

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

 

General
<?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).

Export time series
<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

Export 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.

Import activities
<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.

  • No labels