Introduction¶
This adapter enables the use of WEAP models within the MIKE Workbench.
Concept¶
WEAP is a water resources planning and analysis model based on a lumped, node based approach similar to MIKE HYDRO Basin.
WEAP models are called ‘Areas’ which are limited by boundaries defining the extent of the project area. Each area has a corresponding folder in a user defined folder, the WEAP Area Path. This folder is the folder in which WEAP operates. The folder path can be changed in the registry HKEY_CURRENT_USER\Software\Stockholm Environment Institute\WEAP\AreasPath. The adapter assumes that all files related to the registered WEAP model are in the corresponding area folder.
WEAP comes with a WEAP API which gives the possibility to access all model objects and variables. The adapter utilizes the WEAP API to get and set model variables, vary input time series, run scenarios and read results.
WEAP offers the possibility of defining user-defined parameters and variables. Since the adapter utilizes the WEAP API to access all WEAP parameters and variables, it offers a general approach and supports all default and user-specified WEAP parameters and variables.
WEAP is a singleton software which implies that only one WEAP model can be open and run at the time on one machine. Since the adapter accesses the WEAP API no other WEAP model can be opened or run next to a WEAP model registration or WEAP model scenario run within the MIKE Workbench.
WEAP models can be linked to Qual2K, MODFLOW and LEAP. However, the adapter supports so far only the registration of an un-linked WEAP model.
Prerequisites¶
The configuration and execution of WEAP models in MIKE Workbench using this adapter will require: - WEAP must be installed on the system - All files related to the registered WEAP area must be located within the WEAP area folder in the WEAP area path
Configuration¶
This section describes the formats and details of the WEAP adapter and WEAP model setups.
WEAP model setup¶
No specific configuration of a WEAP model setup has to be followed in order to register it into the MIKE Workbench. The WEAP model setup needs to run successfully within WEAP and the adapter assumes that all files related to the registered WEAP model are in the corresponding area folder.
WEAP models are called ‘Areas’ which are limited by boundaries defining the extent of the project area. Each area has a corresponding folder in a user defined folder, the WEAP Area Path. This folder is the folder in which WEAP operates.
The WEAP model allows saving different ‘Versions’ of a WEAP Area. When registrating the user is prompted which ‘Version’ of the WEAP Area should be registered.
WEAP organizes model runs in scenarios which are also referred to as ‘Accounts’. The ‘Current Account’ represents the base year of a planning horizon and holds all the baseline data for planning and evaluation study. The ‘Current Account’ is by default accompanied by a ‘Active Scenario’ which simulates the evolution of the ‘Current Account’ for the specified time horizon.
The adapter registers all information related to the ‘Current Account’, ‘Active Scenario’ and all other scenarios. However, only the ‘Active Scenario’ is executed when running a scenario within the NB MIKE Workbench. The MIKE Workbench can be used to define different scenarios.
Model Object Types¶
The table below shows how the WEAP model objects are translated within the MIKE Workbench. In the third column it can be seen whether the model object is geo-referenced and how it is visualized in the MIKE Workbench.
Table 4 Mapping between WEAP model objects and NB MIKE Workbench model objects.
| Object in WEAP | Workbench Model Object Type | Geo-reference / Symbol |
|---|---|---|
| River | River | Yes /  |
| Reaches | Reaches | Yes / |
| Diversion | Diversion | Yes /  |
| Reservoir | Reservoir | Yes /  |
| Groundwater | Groundwater | Yes /  |
| Other Supply | Other Supply | Yes /  |
| Demand Site | Demand Site | Yes /  |
| Catchment | Catchment | Yes /  |
| Runoff/Infiltration | Runoff/Infiltration | Yes /  |
| Transmission Link | Transmission Link | Yes /  |
| Wastewater Treatment Plant | Wastewater Treatment Plant | Yes /  |
| Return Flow | Return Flow | Yes /  |
| Run of River Hydro | Run of River Hydro | Yes /  |
| Flow Requirement | Flow Requirement | Yes /  |
| Streamflow Gauge | Streamflow Gauge | Yes /  |
| Key Assumptions | Key Assumptions | No geo reference |
In WEAP, most input variables on a model object can be specified via five different input expressions: user-defined expression using the build-in expression builder, look-up table, time series file using the ReadFromFile function (the ReadFromFile function is only used to import time series), yearly time series or monthly time series using the yearly or monthly time series wizard. All different input methods end up being an expression (string) associated with the corresponding model variable. Regarding input variables, the adapter considers variables associated with an expression containing ‘ReadFromFile’ as input time series and all remaining variables as model parameters for which the expression string is viewable and editable. It is up to the user to verify the correctness of such an expression string.
The adapter will always assume the input parameter type that the WEAP model was registered with. In other words, it does not support to change the input parameter type from model object parameter to input time series or vice versa.
The adapter supports all default and user-defined WEAP model object parameters.
GIS data¶
The adapter geo-references WEAP model objects as they are referenced within WEAP.
WEAP geo-references all model objects and adopts the projection type of the background GIS layers. If no background layers are specified or the schematic is unprojected then WGS84 geographic coordinates are applied. The adapter follows the same logic and adopts the geographic projection of the background GIS layers or applies WGS84 geographic coordinates if no projection is given.
Scematics for point layers are defined in the WEAP API as latitude and longitude. Schematics for the river layer is taken from the shape file WEAPArc.shp.
Time series¶
In WEAP most input variables on a model object can be specified via five different input expressions: user-defined expression using the build-in expression builder, look-up table, time series file using the ReadFromFile function (the ReadFromFile function is only used to import time series), yearly time series or monthly time series using the yearly or monthly time series wizard. Regarding input variables, the adapter considers variables associated with an expression containing ‘ReadFromFile’ as input time series and all remaining variables as model parameters for which the expression string will be viewable and editable. In WEAP, input files are written either in .txt or .csv format and follow a specific format defined in the WEAP manual. The adapter supports all input time series formats that are supported by WEAP itself.
Regarding output variables, the adapter follows a general approach and reports in the MIKE Workbench all output variables as output time series. It does not matter whether output variables are default or user-defined.
States¶
WEAP is water resources planning and analysis model which operates normally on time scales from medium to long term. In other words, WEAP is usually not used for real-time application and hence it does not support the hotstart principal, i. e. specifying initial condition files containing certain model states. Therefore, the adapter does not provide the input condition option for registered WEAP model setups.
Variables and units¶
For model object parameters the adapter reports the unit in a separate property field of the model object parameter.
For input time series and output time series, the adapter supports matching of all standard WEAP variable types and units to the MIKE Workbench types and units. The table below shows an example mapping for likely input time series on the WEAP model object ‘River’.
| WEAP/MIKE Workbench Model Object Type | WEAP Variable Type | MIKE Workbench Type | Supported WEAP Units |
|---|---|---|---|
| River | Headflow | Discharge Water Volume | CMS, CFS, CFM, MGD l ,m3 , gallon, ft3, acre-foot, mill m3 |
| River | TSS Concentration | Concentration | mg/l, g/l, ug/l, lb/AF, ppm, ppb |
| River | BOD Concentration | Concentration | mg/l, g/l, ug/l, lb/AF, ppm, ppb |
| River | Phosphorus Concentration | Concentration | mg/l, g/l, ug/l, lb/AF, ppm, ppb |
| River | Nitrogen Concentration | Concentration | mg/l, g/l, ug/l, lb/AF, ppm, ppb |
The WEAP API retrieves results values in the WEAP default units (see Table below). For output time series, the adapter extracts the model results via the WEAP API and therefore maps the WEAP default units to MIKE Workbench units.
Figure 1 Default units in WEAP
WEAP also offers the possibility of specifying user-defined variables and units. The adapter considers this functionality by providing a file to match user-defined WEAP variable types and units to the MIKE WORKBENCH types and units. The file is called WeapUnits.xml and is located in the MIKE WORKBENCH Platform folder. The user can extend this file with any user-specified variable type and unit. If the content in the WeapUnits.xml file is equal to an entry of the internal variable type and unit mapping then the content in the WeapUnits.xml will be used by the adapter instead of the internal mapping. See below an example of the WeapUnits.xml.
[Code 1.xml]
‘name’ indicates the WEAP variable and unit, ‘valuetype’ the MIKE WORKBENCH time axis type, ‘variable’ the MIKE WORKBENCH variable and ‘unit’ the MIKE WORKBENCH unit. Additionally, the user can specify whether the variable is an output time series or scalar with the parameter ‘datatype’. If ‘datatype’ is not specified the adapter assumes by default an output time series.
Model registration¶
The following illustrates the registration process:
-
From Scenario Manager in MIKE Workbench the user selects “Register model”.
-
The user selects the WEAP model adapter.
-
The user provides the required (and optional ) input to the WEAP Adapter.
a. Specify Model Setup Name
b. Select WEAP area for registration
c. Select ‘Version’ of the WEAP area. If not specified the latest WEAP area version will be registered.
-
Clicking next will start the parsing of the model setup.
-
Then the adapter presents a list of the model objects and associated input and output time series. Clicking Cancel will stop the registration process.
-
Finally the adapter offers the possibility to name the default scenario on the model setup or create the scenario from a template. Clicking Cancel will stop the registration process.
-
Clicking Finish will return the model setup information to MIKE Workbench.