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

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.





Full filepath of the JFlow executable, as installed on the host machine.



Name of the JFlow database, including file extension.            

The full filepath is not required if the module folder structure is maintained.



Number of the GPU device, as machines may have multiple GPU cards.  Default is 0.



Number of flow boundaries.



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.



Number of rainfall inputs.



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.



Output parameter types, separated by commas.  Commonly used options are: depth, hazard_index, velocity, water_level.



LocationID that will be associated with the model results.

The value stated here should match the external ID in the FEWS ID mapping file.



Example .ini file:

.ini file
JflowExecutable=C:\Program Files\JFLOW\JFLOW.exe
[Flow inputs]
FlowNames=Flow_1, Flow_2, Flow_3
[Rain inputs]
[Required outputs]

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="" xmlns:xsi="" xsi:schemaLocation="">
            <!-- general section to specify directories and id maps file -->
                        <description>JFlow fluvial test for the Don</description>
            <!-- burnInProfile - not currently used -->
                        <!-- startUpActivities to remove files from previous runs -->


Export time series from FEWS

The export file must be called export.xml (this is hard coded into the JFlow adapter).

Export time series
            <description>Export flow timeseries</description>
            <!-- exportFile is written to directory named in the General section unless specified otherwise-->
                                    <!-- the data to be exported -->
                                    <timeSeriesType>external historical</timeSeriesType>
                                    <timeStep unit="minute" multiplier="15"/>
                                    <relativeViewPeriod unit="hour" start="-24" end="0" endOverrulable="true"/>
                                    <readWriteMode>read only</readWriteMode>


Execute the JFlow model

Export JFlow model
            <description>Run Jflow Adapter</description>
                        <!-- set path to Jflow adapter executable in the global properties file-->


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
                                                <timeSeriesType>simulated historical</timeSeriesType>
                                                <timeStep unit="nonequidistant"/>
                                                <readWriteMode>add originals</readWriteMode>


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