RIBASIM (River Basin Simulation Model) is a generic model package for analyzing the behavior of river basins under various hydrological conditions. The RIBASIM adapter in FEWS can be used to transfer of hydrological data from FEWS to RIBASIM input timeseries (TMS files) and to transfer RIBASIM calculation results (HIS files) back to FEWS. 

Specific features

Time step definitions

A RIBASIM model can run simulations for predefined time steps of one day ("day"), one week ("week"), ten days ("decade"), half a month ("halfmonth") or one month ("month").

This means that the output of the module which is provided in HIS files is defined in terms of one of these time steps using year/timestep indices. The post-adapter will translate these to FEWS date-time values using the "nonequidistant" timestep unit where the time given reflects the start of each simulation step interval. 

Time series value units

RIBASIM assumes a fixed unit for it's inputs which is given in the runinfo.xml configuration file, the unit defined in the input PI-XML time series is ignored so you need to check that this is equivalent.

RIBASIM adapter binary folder

The following files are part of the binary folder for the Wanda adapter and are provided in the fews-wanda-adapter-bin.<version>.zip artifact of the "install adapters" teamcity builds:

  • fews-ribasim-adapter.jar
  • castor-0.9.5p.jar
  • Delft_FEWS_castor.jar
  • Delft_PI.jar
  • Delft_PI_castor.jar
  • Delft_Util.jar
  • FastInfoset-1.2.6.jar
  • hamcrest-core-1.3.jar
  • log4j-1.2-api-2.11.1p.jar
  • log4j-api-2.11.1.jar
  • log4j-core-2.11.1.jar
  • log4j-slf4j-impl-2.11.1.jar
  • slf4j-api-1.7.13.jar
  • xalan.jar
  • xercesImpl.jar

General Adapter Configuration

General section

The image below shows an example of the configuration of the general section. The following settings are of specific importance for RIBASIM:

  • rootDir: folder where the RIBASIM module is located.
  • workDir: folder where the RIBASIM model is executed.
  • exportDir: folder where the RIBASIM adapter input files (*.xml) should be stored.
  • exportIdMap: the idMapFile for the export to RIBASIM: the external ID's are the Id's in the RIBASIM model
  • importDir: folder where the RIBASIM adapter stores its output file (*.xml)
  • importIdMap: the idMapFile for the import from Wanda: the external ID's are the Id's in the RIBASIM model
  • diagnosticFile: the path of the PI diagnostic file written by the Wanda adapter.

ExportActivities Section

Important for the RIBASIM model and the RIBASIM adapter are the properties of the exportRunFileActivity. These properties provide specific RIBASIM adapter model settings.

  • key - ribasimVersion : the ribasim version used; versions 6  and 7 supported
  • key - tmsUnit : the base unit to use by RIBASIM; 1 = m3/s, 2 = mm/day, 3 = mm/tms, 4 = ppt (when not specified, this is determined from the first input)
  • key - tmsHeader :  the full path of a custom TMS file header to use by the pre-adapter (optional)
  • key - simulationTimestep : the RIBASIM time step to use, supported are DAY, MONTH, HALFMONTH, DECADE, WEEK
  • key - stateExportDir : the directory where FEWS exports and imports the RIBASIM state file (when not specified, the folder containing the InputStateDescriptionFile is used)
  • key - stateFile : the filename of the statefile used by RIBASIM (when not specified it will have the same name as given in the InputStateDescriptionFile)
  • key - runsimpFile : the full path of the control file for RIBASIM (when not specified, runsimp.dat will be created in the working folder)
  • key - runsimpTemplate : the full path of the control file template (when not specified, no "runsimp" control file will be created)
  • key - columnIndexByQualifier : when true, the input time series can be provided with a qualifier (integer) per location to set both the order and header of the columns in the generated TMS file.
  • key - skipMissingInputs : when true, the adapter will skip missing timeseries input files, when false an error will be logged for if input files specified in runinfo config are missing.

As an example General Adapter configuration is not available yet at this time, an example PI runInfo XML file from one of the adapter unit tests is given here:

<?xml version="1.0" encoding="UTF-8"?>
<Run xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wldelft.nl/fews/PI" 
 xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_run.xsd" version="1.24">
    <logLevel>info</logLevel>
    <timeZone>0.0</timeZone>
    <startDateTime date="1990-10-01" time="00:00:00"/>
    <endDateTime date="1991-07-31" time="00:00:00"/>
    <time0 date="1990-10-01" time="00:00:00"/>
    <workDir>$WORKDIR$</workDir>
    <inputStateDescriptionFile>$WORKDIR$/state/states.xml</inputStateDescriptionFile>
    <inputTimeSeriesFile>$WORKDIR$/input/actinflw.xml</inputTimeSeriesFile>
    <outputDiagnosticFile>$WORKDIR$/diag.xml</outputDiagnosticFile>
    <outputTimeSeriesFile>$WORKDIR$/output/ribres.xml</outputTimeSeriesFile>
    <properties>
        <int key="ribasimVersion" value="7"/>
        <int key="tmsUnit" value="1"/>
        <string key="simulationTimestep" value="day"/>
        <string key="stateExportDir" value="$WORKDIR$/input"/>
        <string key="stateFile" value="$WORKDIR$/output/state_out.ini"/>
        <string key="runsimpFile" value="$WORKDIR$/input/runsimp.dat"/>
        <string key="runsimpTemplate" value="$WORKDIR$/input/runsimp_template.dat"/>
    </properties>
</Run>
ExecuteActivities Section

As the RIBASIM model consists of several executable programs that need to be executed in a specific sequence, several executa activities nee3d to be configured, including the executation of the Pre- and/or Post Adapter. An example GeneralAdapter config to illustrate this was not yate available at the time of writing this page.

ImportActivities Section

The import activities as configured will be reflected in the RunInfo xml file eported by the General Adapter as input for the Post-Adapter, see the above example.

TMS file versions

Hydrological timeseries are input in RBASIM using the TMS file format, for which 2 versions have been implemented:

  • TMS 1.01 using RIBASIM time step information (used by RIBASIM 6 and earlier versions)
  • TMS 1.04 using Gregorian calendar (month, day) time information (used by TIBASIM 7 and later versions)

For RIBASIM 7 and later, an exception is for timeseries marked as non-equidistant, these will be converted to TMS 1.01 format, where all "regular" time series use the 1.04 format. Please note that you can have full control over the TMS format version used by using the tmsHeader option, providing your own header (first line of the file). More information is available in the RIBASIM documentation.



Example configuration

Example general adapter configuration file is to be attached 


  • No labels

Disclaimer