Environmental Flow Manager - SRG

The main function of the environmental flow manager is to prioritise and activate actions based on a priority purchasing style conceptual model (Figure 3).

Actions are defined at environmental flow nodes and consist of a set of criteria (system conditions), target response, defined success, and condition function. Actions from various EFNs can be grouped and will then be assessed by the environmental flow manager as a set of actions that need to be activated together. Groups are defined at the EFM level allowing actions for multiple assets to be linked.

The EFM prioritises the actions (or groups of actions) based on the condition and importance. Environmental flow nodes keep track of the condition associated with the actions. 

The Environmental Flow Manager will then determine whether there is sufficient water available to meet each group's needs in priority order, decreasing the amount available to each subsequent priority as the group above reserves water. To do this, the EFM steps through the ranked action list and compares the cost of the action (ie. the volume of water required to deliver the action) to the available water in the portfolios of accounts that can be accessed by the action. If enough water is available, the EFM will commit the water required to meet the estimated cost (i.e. subtracts the volume from the water available), so that the committed water is not available for actions with lower importance. The environmental flow manager flags the action as active to the EFN. The environmental flow manager does not execute actions, it gives permission to the environmental flow node to evaluate the criteria of the flagged (committed) rule and initiate a target response (eg. place orders) when appropriate. Accounts are only debited after orders are made (either order debit or use debit depending on your accounting system).

Figure 3. Expanded Environmental Flow Manager Conceptual Model: Detailed flowchart for the 'Prioritise and activate/flag actions' box in Figure 2.

Environmental Flow Manager Prioritisation Phase:

After the resource assessment phase is complete, the flow manager phase begins. Details of all the phases can be found here under Model Simulation Phases. At a high level the process is as follows:

1. Update functions with time of evaluation of Environmental Flow Prioritisation
2. Decide if the flow manager will run based on the decision point configuration
3. Calculate Portfolio Balances
4. Run the main prioritisation loop
   
   

1. Update functions with time of evaluation of Environmental Flow Prioritisation

All functions are updated at the very start of the prioritisation phase. This is to ensure that any priority, estimated cost, balance adjustment and decision point functions can get updated before we begin the main section of the EFM prioritisation phase.  Any modelled variables used in the function will need to be evaluated at "Current Iteration" to include previous decisons made.

2. Decide if the flow manager will run based on the decision point configuration

The decision point can be used to restrict how often the prioritisation loop occurs. This can be set to every time step or a boolean function. If a function is used it must be set to a time of evaluation of Environmental Flow Prioritisation or earlier.

If a function returns false, each group maintains the state it set to by the EFM during the last time the main priorisation loop occurred (i.e. any enabled groups will continue being enabled, even though the EFM has not run).

3. Calculate Portfolio Balances

The balance of a portfolio is equal to:

Balance = Sum(Account.Balance + Balance Adjustment) for accounts with non-zero share.

There is also the concept of Availabe Water, this will be used in the main prioritisation loop to keep track of water still available.

4. Run the main prioritisation loop

Before any prioritisation can occur, the priorities of all actions associated with EFM are calculated. Only actions that are enabled at the node and are allowed to order are considered by the EFM.

The priority of an action is defined as:

Priority = Condition / Importance

where Condition unless specified by the user is equal to

Condition = EXP(- Time since last successful spell in a successful season/average return interval)

The Priority of a group is equal to the action with highest priority (i.e. lowest numerical value) 

The priorities are only calculated once per timestep. This means any changes to condition or importance during prioritisation iterations will not be used.

Groups to Prioritise = Groups with at least one action (that is enabled or allowed to order)

Next, Addition groups are removed from Groups to Prioritise:

foreach (group in Groups To Prioritise)
{
  if (group.IsActivelyDelivering) 
  {
      group.EnabledByEFM = true
      CommitEstimatedCostToPortfolios(group)
      Groups To Prioritise.Remove(group)
  }
}

CommitEstimatedCostToPortfolios will distribute the estimated cost of a group across portfolios so that the Portfolio.AvailableWater is reduced. This distribution works in a similar way to distribution of water user orders to supply points. That is, the cost will be split across the highest priority portfolios first in the share percentages specified in the portfolio configuration. Lower priority portfolios will only be used once higher priority portfolios have no available water.

Once the priorities are calculated, the main loop begins:

// sort groups by whether they were enabled by the EFM first, then by priority 
SortGroups(Groups to Prioritise)

foreach (group in Groups To Prioritise)
{
   UpdateFunctions()
   // TotalPortfolioAvailableWater is the sum of all of the group's portfolios AvailableWater.
   if (group.IsInSeason && group.TotalPortfoliosAvailableWater >= group.EstimatedCost)
   {
      group.EnableByEFM = true
      CommitEstimatedCostToPortfolios(group)
   }
   else
   {
      group.EnableByEFM = false
   }
}

It is important to note a few things in the above pseudo code. First, groups are prioritised in the following order: Groups that were actively ordering last timestep, groups that were enabled last time the EFM was run then by priority. The ReducePortfoliosByCost function is the same as described above.

The UpdateFunctions() method will update any functions with time of evaluation Environmental Flow Prioritisation. Note: Any modelled variables that need to be used during the iterations must have the Date Range set to Current Iteration otherwise they will not update each iteration.

Prioritisation of actions/groups within the flow manager

The environmental flow manager sorts groups of actions into ascending priority order by examining the priority values generated for each action by the importance and condition functions. The condition is calculated by default as the natural exponent of the number of days since last success divided by the average desired return interval. This can be replaced by a user specified condition function. The importance weighting is calculated using a user defined function, which allows flexibility in the way the events are prioritised and coordinated.

Priority = Condition / Importance

If groups have the same priority value, then they are ranked by the importance values, then by the condition. The priority of a group is considered to be equal to that of the highest priority action within that group. 

If all actions in a groups have an importance of <= 0, the group is disabled.

The environmental flow manager will not enable an action if it returns an importance value that is zero or negative. Groups with any actions with importance > 0 will still be enabled along with any actions in them. To disable a group with multiple actions all actions would need to have importance = 0.

The importance function has no default values and must be specified by the user or else it will be considered to have an importance of 0

The default condition calculation if not specified by the user is EXP(-Time since last successful spell in a successful season/average return interval)

If actions have the same priority (or actions within a group have the same priority), the logic to determine which action should order (and hence pay) is as follows:
order by priority;
then by importance;
then by condition (descending);
then by name

Environmental Flow Prioritisation Phase

All functions are set by default to evaluate at the start of time step, environmental flow prioritisation phase is an advanced usage. If enabling one group has dependencies on another group (e.g. the cost or importance are a function of another group being enabled or not), the functions will need to be evaluated multiple times during prioritisation, and therefore the time of evaluation for the function needs to be set to 'Environmental Flow Prioritisation'. This allows the cost of actions, and hence groups, to be recalculated based on the groups which have already been enabled or disabled. This recalculation occurs each time a group is enabled or disabled.

Enabling of Actions

An action can be disabled at the node and will be ignored by the flow manager, even if it is in a group. 

An action will effectively be disabled if the flow manager does not allocate water to its group, however, the action will still monitor the flow based on action definition. 

When an action is disabled at the EFN, the action has effectively been turned off for the whole run, as opposed to the enabling/disabling by the manager which is dynamic.

Portfolios

Each account within a portfolio can have a balance adjustment specified.  A negative balance adjustment means that water is reserved for later use, or for carry over at the end of the water year. A positive balance adjustment represents an expectation that more water will become available before it is needed during the action's season.

Portfolio Account Balances + Portfolio Balance Adjustments = Balance considered when evaluating against Estimated Costs