Note: This is documentation for version 4.11 of Source. For a different version of Source go to the Space Directory.
Page tree
Skip to end of metadata
Go to start of metadata


The SubSource plugin is developed to run a second Source model at different points during the main model run. This plugin is typically used to forecast water allocations or integrate different time steps in the operation model. The basic concept can be expressed in Figure 1: 

The main model (blue) has steps through the simulation period, using some information from Sub-Model (yellow) to calculate water allocations.

At each call from the main model, Sub-Model (yellow) simulates the scenario such as a worst dry case until the end of the water year (or a defined end time by the user) to estimate harvestable inflows and losses for the main model.

Although the plugin is developed for the specific project, but it is flexible for different needs in more complex water system condition. The main model and Sub-Model can be from in same Source project file or from different Source project file. The developed interface allows the user to choose different parameter values for their requirements. The models can use the catchment mode or the network model. The user can design own data mapping between the main model and Sub-Model. The plugin is convenient to be applied for other projects / purpose.

Figure 1 The basic concept of SubSource

Access the functions of SubSource plugin and the basic procedure

The basic procedure about the access and use of SubSource plugin are described below:

Step 1 Create the Source model using SubSource function

  • Creat a new project
  • Add SubSource plugin from CommunityPlugins\SourcePlugin.SubSource.dll to the created Source project.

Step 2 Create models

  • Creat a main model (scenario) in the current project (e.g. Figure 2(1))
  • Save the project
  • Creat a sub model (scenario) in the current project ( e.g. Figure 2(2)) or another Source project file
  • Save the project.

Step 3 Prepare the connction between the main model and Sub-Model.

  • Make the Main Model (scenario) active
  • Select Sub-model analysis from Analaysis Type dropdonwlist (e.g. Figure 2(3))
  • Click on the Configure (e.g. Figure 2(4)) on the Simulation toolbar to display Sub-Model Analysis Configuration Interface (Figure 3)
  • Set up Sub-Model Analysis Configuration.

Step 4 Save the Source project  file(s) after the Sub-model analysis was set up.

Step 5 Run Main Model.

Figure 2 Access the functions of SubSource Plugin
Figure 3 Sub-Model Analysis Configuration Interface

Configure Sub-Model Analysis

Three additional tabs were developed for setting up SubSource functions (Figure 3):

  • Configuration, which is developed to set up running parameters of the Main Model and to select one sub model from the current Source project or a specified Source project file.
  • Sub-Model Configuration,which provides the interface to define running parameters of Sub-Model.
  • Mapping Configuration, which is the interface to set up the necessary modelling system condition to run Sub-Model and define the data transferring between the main model and Sub-Model.

The functions developed in these tabs are listed below. In this document, the sub model represents the source scenario of Sub-Model with the original condition while Sub-Model is the selected scenario for additional setting up about Sub-Model Analysis or already with additional setting up.

Select Sub-Model

From the Interface of Configuration tab (Figure 3) , there are two frames on the interface: Main Model (upper section) and Sub-Model (lower section). The contents in Main Model frame can be found in Configuring Scenarios. The contents on the Sub-Model frame are as follows:

  • Use Current Project: this tick box defines which Source project file is used to select a scenario as Sub-Model. If it is ticked, the interface will load all scenarios from the current project into Scenario dropdown list for the option. If it is not ticked, Project Path parameter will be activated to define the source project file.

Note that Sub-Model not only can be selected from same or different project where the main model comes from, but also can use the same model (scenario) for the main model.

  • Project Path: this parameter allows the user to choose a Source project file (other than the current project file) as the source of Sub-Model. It is disabled when Use Current Project is ticked.
  • Scenario: the user can select one relevant scenario from this list as Sub-Model. All scenarios in the used Source project file are available for choice.

Generally, Sub-Model can be the scenario selected from the current Source project or a specified Source project file, even can be the same model as the main model.

Set up running parameters for Sub-Model

From the Interface of Sub-Model Configuration tab (Figure 4), the parameters, which are developed to meet different needs in Sub-Model run, are described below:

  • Run Configuration:
  • Override Run Configuration tick box: this tick box allows the user to change the default of Running Configuration names for the selected sub model. When It is ticked, the Configuration dropdown list will be activated.

The Running Configuration names are defined by Running Configuration Management  from Scenario Options.

  • Configuration dropdown list: It provides the available options of Running Configuration names (such as single analysis, linked analysis, custom 1) for Sub-Model. The model will run Sub-Model using selected Running Configuration name from this parameter and ignore default one in the sub model / original scenario. It is only available when the Override Run Configuration tick box is ticked.

Only Analysis Type of “Single analysis" and "Linked analysis" can be used for Sub-Model run and It can't chain together multiple Sub-Models, especially for "Linked analysis".

  • Scenario Input Set: this parameter allows to select different existing Scenario Input Sets for Sub-Model run.
  • Time Step: this parameter provides three options (i.e. From Main Model, From Sub-Model and Custom Time Step) to set up simulation time step for Sub-Model.
  • From Main Model: the time step used in Sub-Model will be same as one defined in the main model.
  • From Sub-Model: the time step used in Sub Model is using the one in the sub model/original scenario.
  • Custom Time Step: this option will display an additional dropdown list for the user to select the required time step. Should note that the user needs to consider the time step used in Main Model for a reasonable matched time step.
 Figure 4 Sub-Model Configuration
  • Start Time: this parameter provides four options, called From Main Model, From Sub-Model, Custom Start Time and Main Model Trigger Time, to set up the simulation start time for Sub-Model. The first three options are self-explained, and their mechanisms are same as those in Time Step. Main Model Trigger Time option is using the time when the main model triggered Sub-Model as the simulation start time of Sub-Model run, and this is a default option. For example, the main model triggered Sub-Model on the time start of 1st September 2000, Sub-Model will simulate the water process from 1st September 2000.
  • Run Period: this parameter provides four options (i.e. From Sub-Model, End of Water Year, Number of Time Steps and Custom End Time) to set up the simulation period for Sub-Model
    • From Sub-Model: the model run period will be adopted from the sub model/source scenario. The run end of time could be different to one defined in the source scenario if the selected start time is not from the source scenario.
    • End of Water Year: the run period will be from the simulation start time to the end of water year. This option will display the additional item (at the bottom of the interface) to define the water year.
    • Number of Time Steps: it defines how many time steps (such as months) and Sub-Model will run the simulation in this amount of time steps.
    • Custom End Time: it allows the user to specify a date when the simulation of Sub-Model will be stopped. This option will display an additional text box to enter a date as the simulation end time.
  • Run Frequency: this parameter provides five options (i.e. Start of Week, Start of Month, Start of Water Year, Number of Time Steps and Custom Trigger) to specify the run frequency for Sub-Model
    • Start of Week: the action to run Sub-Model will be repeated at the beginning of each week.
    • Start of Month: the action to run Sub-Model will be repeated at the beginning of each month.
    • Start of Water Year: the action to run Sub-Model will be repeated at the beginning of each water year.
    • Number of Time Steps: the action to run Sub-Model will be repeated after a certain time interval defined by this parameter.
    • Custom Trigger: it defines a Boolean function to decide whether Sub-Model will be triggered by the main model to start run. The function can be a system conditions such as the water level at one reservoir reached to a certain level (and then Sub-Model will start to run).
  • Water Year: this parameter is linked to options of End of Water Year and Start of Water Year. It is used to specify the start day and month of the water year.

The user needs to consider above parameters together to define their values in a systematic approach.

Note that the user must save the Source project  file because the setting up is functiolized only after the project is saved. Otherwise, Sub-Model will be using the previously saved version of the model.

Linking Main Model running and Sub Model running

On the Interface of Mapping Configuration tab (Figure 5), there are two frames called From Main Model to Sub-Model and From Sub-Model to Main Model. Two frames are utilized to define the data flow direction and data objective/values transferred between the main model and Sub-Model.

Figure 5 Mapping Configuration Interface
  • From Main Model to Sub-Model frame is used to set up data transfer from the main model to Sub-Model and it is happed when Sub-Model is triggered by the main mode to start running:
  • Main Model Value: it is used to define a source value in the main model. This source can be a specific value, a data in data source or a function. It will be signed to the objective function in Sub Model when the main model triggers running of Sub-Model.
  • Sub-Model Function: it is used to specify a function (existed in Sub-Model). This function will adopt the value from Main Model Value when Sub-Model starts running. Although all functions in Sub-Model are available options in its dropdown list, but the user needs to select a corresponding function to transfer the data.

Note that:

  • For the function in this frame, the user can add as many as they need.
  • Each function only allows one value to be used for the data transfer. If the time series is used, the last value will be used.
  • All initial conditions of the water system in Sub-Model need the setting up such as storages' initial volume, water account balance in RAS. These initial values often are passed though the functions from the man model to Sub-Model.
  • Run Initialisation" and "Start Of Run” of Time of Evaluation are specifically developed for this plugin:
  • "Run Initialisation" functions are functions which are used when initialising the run and network elements. Functions which are set to this Time of Evaluation cannot use Model Variables
  • "Start Of Run" will be evaluated after initialisation (reset), and can be used to prime functions and Model Variables with calculated initial values

See the relevant wiki page for more details.

  • The time for the main model is the end of last time step while the time trigged to run the Sub-Model is the start of the time step. For example, the main model (daily time step) trigged Sub-Model (Monthly time step) to run from 1 September 2000. The time for the main model is the end time step of 31 August 2000, and the condition (data) at this time step will be used to setup the initial condition of Sub-Model. The time for Sub-Model is the start of 1 September 2000. This time will be used to receive the initial data from the main model. These concepts are practically for Time of Evaluation.

  • From Sub-Model to Main Model frame is used to define the method of returning Sub-Model results to the main model:
  • Sub-Model Recorder: it is a recorder in Sub-Model to save desired running results as a data source and this source value(s) will be signed to an objective function in the main model when Sub-Model completed a running process.
  • Main Model Function: it can be used to specify a function (existing in the main model), which will adopt the value(s) from Sub-Model Recorder when Sub-Model completed a run process. Again, the user needs to select a relevant function to transfer the data.

Note that:

  • The user only needs to save the recorders, which are necessary for data transfer, in Sub-Model. This can reduce the model running time and the computer memory.
  • The principle of above Note for From Main Model to Sub-Model is also applied for this frame.

Note that the user must remember to save the Source project file before you run the mode because the setting up is functiolized only after the project is saved.

The models also need a prorper deguging, especlly for data trasfer.

  • No labels