You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 12 Next »

Quick-start Guide for Adding an External Module in FEWS

This quick-start guide serves as an example processes for setting up an external module to run in FEWS. It includes the main tasks required to successfully implement any external module, but is in no way fully comprehensive for all modules. As every module is unique, more specific aspects may be required. There are wiki pages for Module adapters supported by Deltares and there is an overview of  Models linked to Delft-Fews.
These steps do not necessarily need to be performed in the order presented.

Assumptions

1. You are using a FEWS-compliant module adapter
2. Data pre and post-processing is not included here.

Steps

1. Use the generalAdapter configuration file to organize the overall structure of your module run. :

General questions to ask are:

  1. What input data is required?
    1. What, if any, of this input data must be provided by FEWS?
      This includes time series data, gridded data, restart files, and additional parameters required by the module.
  2. What is the desired output?
    1. What, if any, of this data must be viewable/used by FEWS?
      This includes time series data, gridded data, and restart files.
  3. Over what period should the model run?
    1. As a hindcast, as a forecast, from a warm state and from a cold state?
      This is specified in the relativeViewPeriod.
  4. How does the model software work and what model definition files are required as input?
  5. How is the model grid defined?

Examples of the generalAdapter for several module adapters can be found here: Module adapters

2. Add the generalAdapter to the moduleInstanceDescriptors.xml file

Note: as of FEWS version 2014.01 specification of the <moduleId> is no longer required.

More information can be found here: ModuleInstanceDescriptors

3. Define the file structure of the module in FEWS

External modules in FEWS are structured in the following way:

%REGION_HOME%/Modules/ bin
                     / adapter_bin
                     / module_directory	Note: The module directory should be defined in with a moduleInstanceId

The module_directory/ may be configured in a variety of ways depending on the module structure. Here is an example:

module_directory / input	Data from FEWS as input to the module
                 / output	Data from the module as export to FEWS
                 / states	States to be passed between FEWS and the module
                 / diagnostics  Directory in which diagnostic files from the FEWS pre-and post adapters are written
                 / workDir	Directory in which module is run, including
                                  - static input files not passed by FEWS, such as bathymetry, observation points, etc.
                                  - model definition template file
4. Create a moduleDataSet file

Copy the module directory to a zipped directory named the same as the moduleInstanceId. Place the zipped directory in the %REGION_HOME%/config/moduleDataSets directory.

5. Create a cold state file if necessary

Copy this file to the %REGION_HOME%/conifg/ColdStates directory

6. Define the module grid in the grids.xml file

More information can be found here: Grids

7. Define the module locations using the locationSets.xml and locations.xml files

More information about locations and locationSets can be found here: Regional Configuration

8. Create a workflow to run the module

More information can be found here: Configuring WorkFlows

9. Add the workflow to the workflowDescriptors.xml file

More information can be found here: WorkflowDescriptors

10. Refresh your configuration and run the module workflow using the Manual Forecast function in the FEWS Explorer

Hit F5 in FEWS to refresh the configuration.

11. Troubleshooting tips

It is possible that a module will run correctly on the first try. First step is to make sure the model runs ok outside of the configuration.

  • Run the model outside of Delft-FEWS
    • Examine the input files generated by Delft-FEWS
      • If they are not ok, solve this issue first
    • Run the model outside of Delft-FEWS, but use the input generated by Delft-FEWS
      • If the model doesn't run properly, examine the model log files and solve the issue
      • If the model does run properly, import the results in FEWS by only using the import part of the generalAdapater.

If the model runs ok outside of Delft-FEWS, the cause is likely in your configuration. Here are some general tips on de-bugging the configuration.

  • When you have selected the appropriate workflow in the Manual Forecast tab
    • Press ctr+r to select specific module instances within a workflow.
    • Press ctr+d to activiate debug mode for specific module instances within a workflow. FEWS will then display additional de-bugging information in the log window.
  • General Adapter
    • Run only certain activities (i.e. only data export) by commenting out unwanted activities in the generalAdapter.
      You make a comment by putting the text between <!- and ->, or in XmlSpy press ctrl-k when you have selected the text.
    • Reduce the relativeViewPeriod within the generalAdapter to shorten run times for de-bugging purposes.
  • The F12 menu contains many tools that may be helpful in examining data, data conversion, and data export.
    Open this menu by pressing F12 when you have the focon the Logs window or the Map tab.
    • Database Viewer (F12 menu, Option J): to view all data imported by FEWS from the module.
  • No labels

Disclaimer