Practice note: Modelling Scenarios using Input Sets

This practice note is one of a set developed to provide consistency and transparency of river system models being used within the Murray-Darling Basin. The practice notes cover modelling practices, such as naming conventions for folder structures to model methods, such as flow routing and residual inflow estimation. The practice notes have been developed by collaborating with the MDBA and the Basin States.

Produced in collaboration with:

This practice note, 'Using Input Sets in Source', describes the agreed general principles and practices recommended when using input sets to adjust data sources or parameters in Source. 

Background

For long-term water planning in the Murray Darling Basin (MDB), the model development process would typically involve the following:

1. Model Calibration. This involves using observed data to determine model parameters for the different subcomponents of Source (e.g. routing parameters, demand model parameters, loss parameters). Specific practice notes on each calibration component cover how a model is calibrated. Following model calibration, the calibration model forms the basis for a set of model scenarios used to support water resource planning. 
2. Modelling Scenarios. Modelling scenarios require the modeller to adjust the model structure (node or links) or parameters to represent a particular set of conditions. Typical model scenarios required in long-term planning in the MDB are
   1. Current Conditions
   2. Without development
   3. Scenario models for rules changes or infrastructure.

When there is no need to change the model structure by adding additional nodes or links, Scenarios can be modelled by adjusting model parameters, functions, and data sources using the Input set functionality in Source (Scenario Input Sets). These input sets consist of a group of data sources and parameter values representing a particular set of conditions used in the source model. The Scenario Input Sets page from the Source User Guide provides details of the different components of the model that can be altered via input sets and how to make these alternations. This practice note does not aim to reproduce this material in the Source User Guide. It aims to provide a set of General Principles that should be applied when setting up your Source model for different model scenarios.  

Note:  If a parameter can not be set via the input set functionality, eWater should be informed so the parameter can be included in those that can be set via an input set. Also, if a parameter can only be set via an input set (such as Ordering Lag time), eWater should be informed to decide if it should be included in the user interface.  

For this practice note, the following definitions apply:

Source Scenario: A node-link configuration used to model a particular configuration of physical structures (infrastructure) or management rules.

Model Scenario: Adjustment of parameters in nodes or links in the Source Scenario via an Input set

General Principles

1. Ideally, only one Souce Scenario or node-link configuration should exist within a .rsproj file. 
   1. This Source Scenario may be a Schematic or a Geographic Scenario.
   2. This .rsproj file should have all the parameters for the default model scenario (or a model run with an empty input set). The default model run would ideally contain the parameters for the final calibration model.
   3. An additional 'Source Scenario' might be required when
      1. new nodes and links need to be included in the model to investigate the particular water management issue, or
      2. when a catchment is split into sections, a Scenario Transfer Node links the model sections together.
         Note: When additional nodes and links need to be added to the model, consideration should be given to adding the additional nodes and links to the existing Source Scenario and setting the parameters of these additional nodes and links so the revised Source Scenario returns the same results for the default model scenario.  This may be preferential to adding a new Source Scenario into an existing .rsproj file.  If a large number of nodes and links need to be added or removed from a particular Source Scenario, the modeller should decide if saving a revised Source Scenario as a new .rsproj file or using an input set to turn the nodes off is the preferred approach.  The pros and cons of the two approaches are discussed below. 
2. Input sets should be used to adjust the default Source Scenario for different Model Scenarios. Model Scenarios may include a without-development scenario or scenarios that investigate infrastructure changes or rule changes on the flow regime. 
3. Consideration needs to be given to the structure of the parent-child-grandchild relationships when setting up the input set structure (See Scenario Input Sets - Child Scenario Input Sets Section)
   
   1. Parent parameters will be applied to the model first. Changes to data sources can only be assigned to the root-level parent input sets.
   2. Children and grandchildren will be applied subsequently. Where parameters are defined in the parent and the child or grandchild input set, the model run will use the parameters at the bottom of the tree (e.g. grandchild parameters will override the parent parameter if the same parameter is defined in both Input Sets)
4. Input sets should have clear and meaningful names (i.e. Without Development Scenario)
5. Input sets should contain metadata (a description of what the input set does)
6. The parameters in the input set should be sorted in a logical order. 

Example approach for setting up a Source model for looking at a particular Model Scenario or set of Model Scenarios

The modeller will need to:  

1. Decide if multiple 'Source Scenarios' are required in the .rsproj file. This should be avoided if possible as it is likely to be unclear to other users which Source Scenario they should use if trying to replicate results.  It may be necessary to have multiple Source Scenarios in a .rsproj file when scenario transfer nodes are used to link Source Scenarios within the .rsproj file. 
2. Decide on the input set tree structure that is best suited for investigating the question being asked. This will require the modeller to:
   1. Describe the model scenario or scenarios required to resolve the question being asked. 
   2. Decide on the most appropriate parent, child, or grandchild relationship for the input sets to answer the question. Data sources can only be assigned to the root-level parent input set. 
3. Develop input sets for the model scenario run or runs. 
4. Store .txt files for key input sets in the model repository ( see /wiki/spaces/SC/pages/51642534) so the model runs can be reproduced.

Structure of the Input Set Tree

When determining the structure of your Input Set Tree, the modeller should aim to use names that make it clear to other modellers what Model Scenario the input set represents. For example, Figure 1 shows the Source Murray Model (SMM) input set tree. This shows three parent input sets (Calibration, Baseline Diversion Limit (BDL) and Without Development). Child and grandchild input sets are then used to look at variations to these three parent input sets. For example, under BDL, there are three child input sets to model: Water Resouce Plan (WRP), Basin Salinity Management BDL (BSMBDL), and Transitional Diversion Limit (TDL) Model Scenarios. 

Figure 1:  Standard model scenarios in Source Murray Model (SMM)

The structure of the contents of the input sets

The contents of the input sets should be set out in a logical order. This may be done by sorting the contents alphabetically or in the order in which the nodes/links appear in the model. In addition, input sets should have comments that allow others to understand what you are trying to achieve with the parameter changes to the model. 

Example of how to set up a without development model scenario using input sets

Background

A Without Development Model Scenario provides a means to estimate the impact of development on the flow regime. It can provide a useful reference model run when understanding the likely impacts of the infrastructure of policy changes.  Ideally, after a model is calibrated, an input set that turns off the infrastructure, demands, and related management rules related will be developed.  This is the 'Without Development' Model Scenario or 'Without development' Input Set.

Typical parameter changes that are required between development and without development scenario

To develop a Without Development Model Scenario, the following model elements must be deactivated by changing the model parameters. In the complex Models used for water resource planning in the MDB, it will not be possible to use the deactivate nodes and link functionality described in the Source User Guide (Schematic Editor - Source User Guide 5.20 - eWater Wiki) as it may cause the model to crash.  Therefore, input sets are used to make the required components of the model inactive.  The Without Development Scenario requires there to be:

1. No consumptive extractions
2. No regulating structures or ordering

Input sets can be used to:

1. Set orders to zero, including setting all demand models to zero, setting minimum flow requirements to zero and turning off all trade.
2. Set all regulating structures to fully open. 
3. Disable storage and weir nodes by setting the initial volume to zero, disable internal spilling, adding upstream routing where appropriate (to simulate any time delay modelled in weir nodes), and setting the outlet curve to a large capacity.
4. Set appropriate system inflows.

Some examples for setting up input sets for a without-development model

Notes:

1. The list provided below is not exhaustive. The modeller should consider undertaking appropriate QA checks to ensure that the input set has turned off all development within their model. 
2. The examples below are for a single node or component in the model. To disable all nodes of a particular type, the input set will need to contain a complete list of the nodes of that type.  An easy way to create an input set is to use the feature table in Source to export a list of the nodes, and then create the contents of the input set using a program external to Source (e.g. excel). 

Setting Orders to Zero

Set all regulating structures to open fully

Disable storage and weir nodes

All outlet paths are set to unlimited capacity so all inflows will spill, as shown below.

Set appropriate system inflows