Note: This is documentation for version 5.16 of Source. For a different version of Source, select the relevant space by using the Spaces menu in the toolbar above

Environmental Flow Node - SRG

Owned by Meryl McKerrow
Last updated: 29 Nov 2022 by Jin Wang

The functionality provided by the environmental flow node in Source is designed to model existing and proposed water sharing arrangements that include environmental flow rules.

Source models the use of water by a combination of supply point and water user nodes. The environmental flow node (EFN) operates on a time-step basis generating demands for the environment. 

The EFN contains two types of environmental actions and allows modellers to construct an environmental water requirement by using combinations of these, rules can be grouped if required. The two types are:

  • Spell based - A spell can be defined as a period of time that the flow has a set of desired characteristics. The environmental flow node has been designed to deliver additional (environmental) flow i.e. flows over a specified threshold. Limits to flows may be set up elsewhere in the Source functionality. This type of action can by used to specify floods, freshes (usually associated with a recruitment event such as to trigger fish movement, water floodplain vegetation), a flow pattern or a minimum flow (usually applied to maintain minimum habitat requirements); and
  • Translucency - specifies the flow requirements in terms of some other time series, usually the release from a dam based on the inflow of the dam. Translucency can also be configured to represent minimum flows

Common concepts to both types of actions are- 

  • Season: the period of the year over which the rule should be considered (eg is this a winter flooding rule only);
  • Reference Flow: A representation of flow, often higher in the system or an earlier recorded 'natural' flow pattern, that can have various relationships configured in relation to it;
  • Start Threshold: Required expected flow for action to be triggered. The expected flow at the environmental flow node is the maximum of the Minimum Constraint at the upstream node and the Order at the downstream node.
  • End Threshold: A flow threshold below which the flow should fall to consider the action finished. An action or ordering period will end either when the end threshold is reached or the season has ended.

Scale

The Environmental Flow Node is applied at a point scale and operates on a daily time-step.

Provenance

The Environmental Flow node functionality was conceptualised in extensive consultation with the environmental water management organisations associated with the Murray Darling Basin in 2017.

Version

Source v4.3

Dependencies

The Environmental Flow Node is applied as a stand-alone node, which must be connected to a surface water system. To link environmental orders to accounts, or to prioritise actions across the system, an environmental flow manager and resource assessment system is required. 

Assumptions

    • Water requirements are not additive: Increased river flows and return flows can contribute to other actions (return flows can be re-credited as per normal accounting rules). 
    •  Actions can be co-dependent: A flow rule can be conditionally contingent on another flow rule also being met. This has to be configured through the importance and cost functions.
    • The highest priority water demand is for flow rules which have commenced but not yet completed. If a flow action has started, then the continuation this flow action has precedence over activation of a new flow rule.

Theory

The Environmental Flow Node is used to generate orders to meet in-stream environmental requirements at an individual asset. It can also be used to monitor defined event patterns. The rest of this document assumes you are intending to place orders that will supplement existing flows to create specific patterns of flow events. The desired flow patterns are defined by configuring one or more actions including start criteria, desired flow rate and frequency, as well as criteria for success of the action. 

The Environmental Flow Node (EFN) provides a way of capturing prescriptive descriptions of the patterns of water that the environment requires. These definitions of watering patterns are captured as ‘actions’ within the EFN, many combinations of actions can be prescribed for a single EFN. An action is a combination of a definition of the desired flow rate, duration, frequency and timing of beneficial flow events. The two types of actions presented in the EFN have been designed to capture the most commonly defined environmental flow requirements specified in environmental flow studies and water regulations. These two types of environmental actions allow users to construct a collective environmental water requirement by using combinations of actions. The two action types are:

  • Spell-based, which includes:
    • Baseflow: specifies a minimum flow; usually applied to maintain minimum habitat requirements
    • High Flow/Flood: specifies a flood fresh; usually associated with a recruitment event such as to trigger fish movement, water floodplain vegetation, moving sediment deposits
    • Pattern: specifies a pattern of flow; used to define multi-peak events.
  • Translucency: specifies the flow requirements in terms of some other time series, usually the release from a dam related to the natural inflow to the dam. Translucency is effectively a simplified version of the spell based action. 

Spell Based Action

A High flow/Flood action defines a flow requirement above a set level. The parameters for defining a flood/fresh flow component are illustrated in Figure 4 and described below.

Figure 4. Illustration of parameters used to describe a High Flow / Flood action

A spell can be defined as a period of time that the flow has a set of desired characteristics.

A high flow spell is defined by the period of time the flow is above the target. In figure 4, (8) represents the target flow rate, and (2) represents the length of a spell.    

A season (1) is the period of time within a water year, that you desire spells to occur. Users can specify characteristics to determine the occurrence of spells desired to complete a successful season within a water year, including the number of spells, minimum independence interval (4) and desired successful season frequency (return interval). 

Once you have specified what characteristic you want, the next step is to specify the intervention you are going to take to achieve the desired outcomes defined above. The start threshold (7) defines the point after which an order may be used to augment the flow. The order is based on the rise (5) and fall (6) characteristics, the target flow (8) and minimum duration required (2,3). It is possible to extend the Minimum Spell Duration by way of a Boolean function. This allows variable spell duration's to be defined to represent various environmental flow requirements throughout the year.


Generate demands and orders for actions

The environmental flow node will generate demands and orders for actions. An Environmental Flow Node (EFN) can be assigned to an Environmental Flow Manager (EFM) or can operate in isolation. In case the actions are managed by an EFM, the EFN will only order actions that are flagged by the EFM as active. If no EFM is used, the EFN will activate actions depending on their desired return interval. In both cases, the EFN will try to piggy back on flows based on a user-defined flow threshold. That is, an action will still calculate the demand for that action even if the EFM has disabled the action. This is to allow for natural spells to be validated. A user can also determine if and when an action should be forced. If a flow threshold for piggy backing is not reached and an action is able to be forced, the EFN will start the action at the last possible day of the season.

Evaluate success and condition of action events

The success of an event is calculated by three user-configurable properties:

  1. Proportion of target
  2. Proportion of duration
  3. Proportion of volume

Proportion of target:
This specifies the minimum flow rate that must be achieved each timestep to consider the action succesful.
 For example, if a spell has a target flow of 50ML/d and a Proportion of target = 50%, the node must receive at least 25ML/d every timestep during an event to be a success

Proportion of duration:
This specifies the proportion of timesteps  in an event that meet the proportion of target criteria. For example, if a spell is configured with:
  • Target flow = 50ML/d
  • Proportion of target = 50%
  • Proportion of duration = 70%
  • minimum spell duration = 10 days
For this spell to be successful, the node must have received 25ML for at least 7 days.

Proportion of volume:
This specifies the minimum total volume that the node must receive over the event. An event is successful if the cumulative volume received over the event is greater than the cumulative target volume x Proportion of Volume. For example, if a spell is configured with:
  • Target flow = 50ML/d 
  • Proportion of volume = 70%
  • Minimum spell duration = 10 days
For this spell to be successful, the node must receive 50*10*0.7 = 350ML.

All three of these must be satisfied for the event to be considered a success

If the end spell if it will fail option is turned on, a spell is stopped if success is determined to no longer be possible. Since this is calculated during spell execution, only proportion of target and proportion of duration criteria are used.
This is done by keeping a counter of the number of timesteps that were successful based on the target flow criteria. If this counter is greater than the minimum spell duration x (1- Proportion of duration) (i.e. the maximum number of failure timesteps) then the spell is stopped.

The success of an action's season is configurable to be equal to or less than the required number of spells in a season.
Success will be calculated as the model runs and days since last success will be recorded for use in the calculation of condition.

The user can specify a condition function, but by default, the condition is calculated as

EXP(-time since last successful / average return interval).

Antecedent Condition

with Average Recurrence Interval being calculated from the Desired Frequency:

For example, desired frequency is 2 in 3 years, the Average Return Interval is 365 / (2/3) = 547.5 (days).

The Antecedent Condition equation returns a value between 0 and 1 (0 is poor condition and 1 is good condition). The user-defined function is not restricted to return a value between 0 and 1, however, it is strongly recommended to consider the implications before changing the output range.

Antecedent Condition is used by the EFM to determine the priority of an action. 


Rise and Fall Calculations:

There are 3 methods provided to calculate the rise and fall duration and demand volumes:

  • Days
  • Rate
  • Percentage

Each method simply calculates a duration and a demand based on two flow values. In the case of rise, these flow values are the expected flow and the target volume on the first timestep the spell was in the Rise Phase state. The expected flow will be either minimum constraint or downstream order depending on what triggered the spell (i.e if triggered by an upstream constraint, the expected flow will be the upstream constraint). In the case of fall, the two flow values are the Target Flow and the Fall Target.

Note: Rise and fall will only be used for 'managed' spells. i.e. a spell that the EFN will place an order for. This means for natural spells, the rise and fall duration is effectively zero. Also note that it is possible for a managed spell to be successful by downstream orders or upstream constraints. If it is, the EFN will still wait for the rise and fall duration before a new spell is triggered. This means depending on the type of spell, some recorders will be updated slightly differently (e.g. Number of successful spell in a season)


Days

The Days method simply calculates a linear increase (or decrease for fall) between two flows

Rise:

Duration =  day value or zero if the expected flow >= target flow.

let increment = (target flow - expected flow) / days

Environmental Flow Requirement = Min(target flow, expected flow +  increment * days in rise phase)


Fall :

Duration = day value or zero if the target flow <= Fall Target

let decrement = (target flow -Fall Target) / days

Environmental Flow Requirement = Min(target flow, expected flow  - decrement * days in fall phase)


Rate

Rate method increments at a constant rate regardless of the initial expected flow.  

Rise:

Duration =  (target flow - expected flow)/ Rise Rate or zero if the expected flow >= target flow.

(expressed in  the code or a function: Duration = Math.Max(0, Math.Round(target flow - expected flow)/ Rise Rate)) )

Environmental Flow Requirement = Min(target flow, expected flow +  Rise Rate * days in rise phase)


Fall :

Duration =  (target flow - expected flow)/ Fall Rate or zero if the target flow <= Fall Target

Environmental Flow Requirement = Min(target flow, expected flow -  Fall Rate * days in fall phase)

 

Percentage

The percentage method increases or decreases the demand by a constant percentage every day.

Rise:

Duration =  day value or zero if the expected flow >= target flow.

Environmental Flow Requirement = expected flow * (1 + increment) on the first day

                 last timesteps demand * (1 + increment) on the following days.

Fall :

Duration = day value or zero if the target flow <= Fall Target

Demand = expected flow * (1 - decrement) on the first day

                 last timesteps demand * (1 - decrement) on the following days.


Translucency Action

The logic around decisions to create demand associated with a translucency action is as follows

  1. Are we in the specified season?
  2. Are we in event?

The action is 'in event' if Reference flow > Start threshold 

Any time the reference flow < end threshold, the event is ended. 

Target flow is reference flow * % translucency.

Where:
reference flow = the flow defined by a function (such as reservoir inflow) 
Water demand(t) = min(Target flow - ForecastFlow(t), available water)

Note. Where a Translucency action uses forcing environmental water rather than held environmental water, the action should not be associated with a flow manager.

Translucency Reference Flow 

A translucency reference flow is often used to represent an inflow to a storage. The translucency action is configured below the storage, too allow for flow patterns to be replicated downstream. The assumption is that the reference flow is occurring at the closest storage (ie minimum travel time).  

Evaluate success and condition for translucency action events

Success is defined by the total volume delivered over the demand period (based on required flow duration and rate) and is expressed as a percentage.Translucency action success is fixed at 100% for every time step, and over the event 100% of timesteps much be succesful. This sets the time since last succesfull event For example, if the threshold is set at 80%,andeventthatdelivered80% success or more is flagged as successful. This allows for flexibility in the definition of success. Success will be calculated as the model runs and days since last success will be recorded for use in the calculation of condition.

The user can specify a condition function, but by default, the days since last success divided by the desired return interval will be used as a measure of condition. 

Life cycle of a spell

There are 9 states a spell can be in:

  1. Dormant
  2. Waiting for trigger
  3. Rise Phase
  4. Main spell phase
  5. Finished ordering
  6. Fall phase
  7. Complete
  8. Interrupted
  9. Forcing

Every spell starts in the dormant state and transitions through various states during the course of a season. The transitions occur either in the constraint, ordering or flow phase of the environmental flow node. Each phase and its effect on state is described in more detail below.

Dormant

Each spell starts in the dormant state. At the beginning of each start of the season, the node creates the number of spells equal to the user set Number of spells in season property. These spells are put in a queue.
Constraint Phase
The node will check the current spell, if it is empty, the spell on the top of the queue is removed as designated as the current spell. The spell will then transition from Dormant to Waiting for a trigger and run the Waiting for trigger constraint phase (and future phases).
Ordering Phase
In this state, nothing is done during the ordering phase
Flow Phase
In this state, nothing is done during the flow phase.

Waiting for trigger

When a spell is in the Waiting for trigger phase, it is waiting for the user-defined start threshold to be met. It should be noted that a spell only considers constraints and orders external to the node for triggering. This means that spells cannot be triggered by other spells within the node.

Constraint Phase
If the minimum interval between forced spells is non zero, the node will check the number of timesteps between now and the last successful spell. If this value is less than the minimum interval value, nothing will be done even if the threshold is met.
The spell will check if the minimum upstream constraint is greater than the spell start threshold for this timestep (since it can be a function). If this condition is met, the spell will transition to the Rise Phase and run the Rise phase's ordering phase (and future phases).
If there is not enough time in a season to complete this spell (minimum spell duration + now > end of the season), then the spell transitions to the Interrupted state. Since this is checked on spells before they reach any further states, spells will never run out of time in a season once they are in a state later than the Rise Phase.
Ordering Phase
If the minimum interval between forced spells is non zero, the node will check the number of timesteps between now and the last successful spell. If the difference between these times is greater than the rise time duration (see below), nothingwill be done even if the threshold is met.
The spell will check if downstream orders are greater than the spell start threshold for this timestep (since it can be a function). If this condition is met, the spell will transition to the Rise phase and run the Rise phase's ordering phase (and future phases).
Flow Phase
In this state, nothing is done during the flow phase. If a spell is in this state during the flow phase, it means that the threshold has not been met. If it has been met, the spell will be in a different state at this point in time.

Rise Phase

During the rise phase, orders are placed to try to transition between the current flow at the node and the target volume. If there is not rise defined, then the spell will transition into the main spell phase.

Regardless of what rise method is used, a rise phase can be broken down into how many timesteps are required, and what volume is required to order. The spell will transition to the Main Spell Phase once this spell has been in this state for the calculated number of timesteps. It does not matter if the rise phase orders are successful or not.

Constraint Phase
If the remaining timesteps required for the rise phase is zero, the spell will transition to Main Spell Phase and run the Constraint Phase.
Otherwise, a demand value is calculated based on upstream constraints.

Ordering Phase
A demand value for the rise phase is calculated based on the downstream orders.
Flow Phase
In this state, nothing is done during the flow phase.


Main Spell Phase

During this phase, demands are calculated to be equal to the target value. Demand values will be generated for at least the minimum spell duration.  If the extend spell option is used, demands will continue to be placed until the value evaluates to false.

Constraint Phase
The demand during the constraint phase will be set to the target flow for timestep.
Ordering Phase
The demand during the ordering phase will be set to the target flow for this timestep.
Flow Phase
During the flow phase, the received flows are compared to the demands.
If the End Spell if it will fail option is enabled and a spell is not considered successful (see section on success for how this is calculated), the spell will transition to the Complete state.
If all orders for this spell have been placed, the spell will transition into the Finished Ordering Spell Phase and continue its flow phase. The Spell is considered
If the spell has been in the main spell phase for at least the minimum duration, spell success is checked. This means that success includes timesteps outside of minimum spell duration (e.g. due to end thresholds not being met or extend spell duration flag).

Finished Ordering Spell

During this phase, all demands have been made, the node is just waiting to receive them (due to travel time). Once they are received, a spell in this state will

Constraint Phase
No further demands are required so this phase will do nothing.
Ordering Phase
No further demands are required so this phase will do nothing
Flow Phase
In this phase, spell success is checked against the received water as per Main Spell Phase.
Once all demands have been received (successfully or unsuccessfully), the spell will begin checking the received flows for end threshold.
End threshold is met when the received flow at the node is less than the End Threshold value for Duration required below threshold timesteps. If this condition is met, the spell moves into Fall Phase state.

Fall Phase

The fall phase operates in a similar way to the rise phase. Demands will be calculated

Constraint Phase
The fall demand is calculated based on upstream constraints and the target flow of the last timestep in the main spell phase. See the rise and fall section for more details.
The first timestep the spell is in this phase, a fall duration is calculated. This is used in the fall phase to count how many timesteps the spell has been in the fall phase
before finishing the spell.
Ordering Phase
The fall demand is calculated based on downstream orders and the target flow of the last timestep in the main spell phase. See the rise and fall section for more details.
Flow Phase
The spell checks how many timesteps it has been in this phase, compared to the number of timesteps required in the fall phase (calculated in the Constraint Phase). Once this condition is met, the spell transitions to the Completed State.

Completed

This is an end state for the spell. If a node sees it's current spell is in this state, it will get the next spell out of the queue.

Interrupted

This is an end state for the spell. If a node sees it's current spell is in this state, it will get the next spell out of the queue.

Forcing

This state is used to immediately move a spell into the Waiting for Trigger state. This will only get used if Allow forcing of spells is on and the number of seasons that have failed is greater or equal to the user specified number of season failures before forcing. These spells will be added at the latest possible timestep that will allow all spells to successfully complete.

Ordering

Without a flow manager:

The order placed in the system without a flow manager depends on min upstream constraint or downstream orders.

If the minimum constraint is greater than the action with the maximum demand then the order placed in the system will be zero.

Otherwise, the order will be the maximum demand minus the downstream order.

With a flow manager:

The order placed in the system with a flow manager depends on min upstream constraint or downstream orders and other actions at the node with a higher priority (specified in the flow manager).

If the minimum constraint is greater than the action with the maximum demand then the order placed in the system will be zero.

Otherwise, the order will be the maximum demand minus the downstream order and the order of any other action with a higher priority.

This ensures that actions in higher priority groups will debit their accounts before lower priority actions and that the total order does not exceed the action with the largest demand.

Input Data

Refer to the Source User Guide for detailed data requirements and formats.

Output data

The model outputs daily surface and base flow. This may be saved in ML/d, m3/s or mm/d. See environmental flow recorders for r\descriptions