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. Please see this wiki and this wiki for more information regarding module adapters supported by 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:
a) What input data is required? 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.
b) What is the desired output? What, if any, of this data must be viewable/used by FEWS? This includes time series data, gridded data, and restart files.
e) Over what period should the model run? As a hindcast, as a forecast, from a warm state and from a cold state? This is specified in the relativeViewPeriod.
c) How does the model software work and what model definition files are required as input?
d) How is the model grid defined?
Examples of the generalAdapter for several module adapters can be found here: Module adapters
2. Add the general adapter to the moduleInstanceDescriptors.xml file.
Note: as of FEWS version 2014.01 specification of the moduleID is not required.
More information about moduleInstanceDescriptors 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/"ModuleInstanceID" / bin
/ adapter_bin
/ module_directory The module directory should have the same name as the corresponding 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
/ input bathymetry files, observation points files, etc. not passed by FEWS
/ model definition template file
/ diagnostic file of the module
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 about grid definitions 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 about workflows can be found here: Configuring WorkFlows
9. Add the workflow to the workflowDescriptors.xml file.
More information about workflowDescriptors can be found here: WorkflowDescriptors
10. Refresh your configuration and run the module workflow using the Manual Forecast function in the FEWS Explorer.
11. Troubleshooting tips.
It is highly unlikely that a module will run correctly on the first try. Here are some general tips on de-bugging the configuration. Note: These tips will not help if the module itself poses an issue.
- Tip: Press ctr+r to select specific module isntances within a workflow.
- Tip: 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.
- Tip: When de-bugging, reduce the relativeViewPeriod within the generalAdapter to shorten run times.
- Tip: You can select to run only certain activities (i.e. only data export) by commenting out unwanted activities in the generalAdapter.
- Tip: Use the Database Viewer (F12 menu, Option J) to view all data imported by FEWS from the module.
- Tip: The F12 menu contains many tools that may be helpful in examining data, data conversion, and data export.
