Note: This is documentation for version 5.0 of Source. For a different version of Source, select the relevant space by using the Spaces menu in the toolbar above
Off Allocation SRG
Document History
Date | Author | Revision | Description of Change |
Linda Holz | 0.1 | First draft | |
Oct 2011 | Chris Wilson | Review comments provided by Chris Wilson | |
Apr 2012 | D Black | 0.2 | Extensively modified, using Specification version 0.8 as the basis but also incorporating feedback from Chris Wilson where possible. Needs reviewing again and further input by SMEs, especially as there is one code segment in it (from the specification) which needs to be converted into SRG description. |
Mar 2015 | D Black | 0.3 | Incorporates feedback from Chris Wilson and some input from Geoff Podger re thresholds (Figs 1 and 2). |
Apr 2015 | D Black | 0.4 | Incorporates 2nd round of feedback from Chris Wilson; 0.4a includes modified figs 1 and 2 incorporating feedback from Perlita |
May 2015 | G. Podger | 0.5 | Review of methodology |
Mar 2017 | G.Podger | 0.6 | Align method with code implementation in Source |
Overview
Description and rationale
Off-allocation flows are typically those flows that are in excess of regulated requirements. A number of different types of rules are used to share off-allocation flows in practice. The off-allocation node (OAN) in Source enables these rules to be replicated.
Scale
The off-allocation node manages access to flows in a specified reach of the river and can also share flows with downstream off allocation reaches.
Principal developer
Several jurisdictions in Australia have developed model representations of off-allocation, starting from the 1980's with refinements continuing since then in response to evolving water management needs. The representation in Source has been developed by eWater, based on these earlier representations.
Scientific Provenance
A number of permutations of off-allocation have been implemented by various Australian states over many years. Within a given jurisdiction it is not uncommon for there to be differences in the way off-allocation is implemented between river valleys. The representation of off-allocation in Source is designed to replicate these practical implementations and also provide sufficient flexibility to accommodate new changes if required.
Version
Vx.x.x has complete functionality
Dependencies
Requires a Resource Assessment System (RAS).
Requires that the account distribution method is used at the Water User Node and other relevant node types.
If a splitter is used, an off-allocation node cannot manage off-allocation orders down both arms of the splitter. This means that an off allocation node has to be placed separately downstream of each arm of the splitter.
Assumptions and Limitations
Table 1. Assumptions and constraints applying to off-allocation
No | Assumption/Constraint |
|---|---|
01 | An off-allocation system (OAS) must always be 'linked' to a Resource Assessment System (RAS); i.e. an off-allocation system cannot exist without a RAS. |
02 | There is no requirement to have an off-allocation system within a Resource Assessment System. |
03 | Flow travel time is taken into consideration but 'Routing attenuation' is not considered as part of the off allocation system functionality. |
04 | A water user can only have one off-allocation account per off-allocation system (but could have multiple off-allocation accounts via additional off-allocation systems). |
05 | An off-allocation node must be linked and configured via an account type, otherwise the node cannot be used to allocate off-allocation water within the system. |
06 | An off-allocation node can only have one account type per OAS (but may also have an account type in another OAS/RAS). |
07 | Only one OAS can exist per RAS. |
Definitions
Account Type | The account type is a grouping structure for the off-allocation accounts that have water allocated to them from a specific OAN. |
Account | Each water user who requires access to off-allocation flow from a particular point (i.e. OAN) in the river system will require an off-allocation account at that node. Each account must be associated with an account type, but each account type can be associated with multiple accounts. |
Active storage volume | The storage volume above the lowest outlet |
Allocation | The volume of off-allocation water made available for a water user to extract in a time step. |
Annual Usage Limit | A volumetric cap on combined usage of all accounts in a given off-allocation account type. The cap is apportioned to individual accounts in the ratio of shares held to the total number of shares in the off-allocation account type. If no value is specified then the usage is unlimited (i.e. subject to water availability and a User Limit and Annual System Cap if specified, but otherwise not constrained by factors such as supplementary entitlement). |
Annual System Cap | A volumetric cap on combined usage of all off-allocation account types in an off-allocation system, representing the maximum usage permitted for the off-allocation system in the water year. If no value is specified then the usage is potentially unlimited (i.e. subject to water availability and Annual Usage Limits if specified, but otherwise not constrained). |
Consumptive Users | Water users who extract flows. |
Flow Threshold | A total flow or a flow in excess of regulated requirements in ML/d at which an off-allocation flow event is declared to start and to end (subject to any maximum flow constraint the modeller may specify). Start and end thresholds may differ. |
Modeller | The person using the Source software. |
OAN | Off-allocation node |
OAS | Off-allocation system |
Off-allocation flow event | When flows are above the threshold for the off-allocation flow period. |
Off-allocation flow period | The time between the start and end of an off-allocation flow event. |
Off-allocation flow volume | The daily flow volume in excess of the flow threshold or regulated requirements (as specified by the modeller). |
Off-allocation request | An order generated by a Water User via Supply Point Node, Storage Node, Bulk Licensing Node, Environmental Demand Node or Off-Allocation Node. For example, the Water User Node generates an off-allocation request on top of its regulated orders that represents the amount of water that could be taken to fill an on farm storage to the target airspace (limited by pump capacity). It may also be generated by a crop to fill the soil moisture to an opportunistic soil moisture target or pond to a maximum pond level. |
Order | A regulated request made by a Water User Node (or other system regulating component) for a volume of water to be supplied at a specified time into the future. |
Priority Level | Modeller defined priority for each downstream water user at a particular OAN which has a demand for off-allocation water. |
Regulated Requirements | Existing orders and essential requirements (adjusted for delivery losses and gains). |
Reserve Proportion | The modeller may wish to restrict the available off-allocation volume by a set proportion. |
Storage Volume | The volume of water that can be held in a storage i.e. below the lowest uncontrolled spillway. |
Supplementary entitlement | For each account, this is derived from the number of unit shares held. |
Threshold | Threshold is the specified flow value supplied by the modeller (start threshold used for initial time step in an off-allocation flow event and end threshold applies for each subsequent time step). The threshold may be defined by an function. |
Translucency | A process for passing inflows through a storage according to a range of criteria (often used to mimic parts of the natural flow regime). |
Unit Share | Dictates the share of available water an account can be allocated. Each account must be configured with a value for the total number of shares held. |
User Limit | This is a hard rate limit that can be enabled per user. For example, the modeller could specify a specific supply point to have a user limit of 5 ML/day regardless of what other caps are used. It is set up in the accounts table. |
Volume allocation level | Modeller defined volumes of off-allocation water versus user priority at an OAN (see Table 5). For example this allows particular users such as the environment to be given a higher priority in a dry period. |
Water user | A shorthand term used in this SRG entry to collectively refer to a Water User via Supply Point Node, Storage Node, Bulk Licensing Node, Environmental Demand Node or Off-Allocation Node. |
Theory
Overview
An off-allocation flow sharing system is described in Source by:
An accounting and sharing system
Surplus flow allocation
Off allocation requests and withdrawals
Off allocation accounting and sharing is specified as an account type within a resource assessment system. On this basis, where applicable, it inherits the ownership of the resource assessment system, which is taken into account when water is allocated. The off allocation system (OAS) properties that can be configured include:
The start of the off allocation water year,
Whether the sharing arrangement is on the basis of trying to equalise access opportunity to account holders, however, the Equalise Shares function is no longer accessed by the user since version V4.10.2 of Source.
Optional annual system cap on the amount of off allocation water that can be allocated in a water year,
Optional rules for resetting account balances when specified storages spill,
Configurable list of storages that are considered for off allocation access, and
Off allocation accounts.
The off allocation accounts are related to off allocation reaches which are defined by off allocation nodes (OANs). An OAS may be associated with multiple OANs. The off allocation properties for an associated OAN that can be configured include:
Optional annual usage limit,
Table of off allocation volume thresholds and associated priorities for downstream water users, and
Table of downstream water users and associated shares, initial usage, optional use limit and optional delivery efficiency override.
The OAN may only be associated with water users that are downstream of the node. The type of water users that place off allocation requests include:
Water User supplied via Supply Point Nodes,
Bulk Licensing Nodes,
Environmental Node,
Storage Nodes, and
OANs.
The OAN is used to determine off allocation volumes and to share this volume according to the rules specified in the OAS. The OAN properties that can be configured include:
The off allocation trigger method,
Start flow threshold for off allocation to be declared,
Optional end flow threshold for off allocation to cease,
Optional maximum flow threshold to cease off allocation,
Optional proportion of off allocation to reserve i.e. not allocate,
Optional start and end dates for the off allocation season, and
Optional limit on off allocation requests to be passed to upstream OANs.
Modelling of off-allocation flow sharing in Source comprises three major components: firstly, the water user off allocation request to the system (source requests) which are adjusted for anticipated losses and gains in the ordering phase and reach the OAN as a target request. The ratio between the source and target request is considered to be the delivery efficiency, which may be optionally overridden. Secondly at the OAN volumes of water available to share are considered, and finally, the accounting and sharing of that water to meet water user requests. Off-allocation flow sharing is triggered when the flow volume at an OAN exceeds the defined criteria for an off-allocation flow sharing event. Noting that this may be further constrained by exceeding an optional maximum flow limit. A proportion of the volume of water above either orders or the flow threshold is shared between water users according to the rules specified in the OAS.
As a downstream OAN may have an account at an upstream OAN. In the case of a confluence it is possible for a downstream OAN to have accounts in both upstream branches. In such cases the OAN requests are sent to both upstream OANs. As the requests are met at one upstream branch the subsequent request in the other branch is correspondingly reduced ensuring that the request is not exceeded i.e. not double accounted. Note this will give priority of allocation to the upstream branch which is processed first.
The priority of access of different water users is associated with off allocation volume thresholds. There may be multiple increasing thresholds with different priorities at each threshold. This functionality has been included to represent the extent that events may reach. The first threshold represents a volume that is sufficient to meet the first extent of sharing e.g. the current off allocation reach. Consequently if the volume to be allocated is less than this amount then no sharing occurs. Subsequent thresholds recognise that the event may be able to reach further down in the system and also that the additional users may have a different priority e.g. filling of a storage. The thresholds are treated as a step function i.e. once equalled or exceeded then the current threshold priority applies.
Allocations to accounts depend on the available water, allocation priorities, ownership in the system, usage caps and water user requests. Conditions for off-allocation flow sharing such as water quality or environmental health factors can be configured by the modeller entering a function to define a flow threshold based on reference water quality or flow at a point or points in the river. Environmental requirements can be treated as water users who have an off-allocation requirement that can then be prioritised by the modeller or, alternatively, the modeller can define a function to restrict the triggering of an off-allocation flow event based on water quality, account allocation percentages or water sharing rules.
Off allocation requests
Off-allocation requests are generated by a range of previously mentioned downstream water users. The purpose of the request is largely dependent on the type of water user.
Off allocation requests from water users connected via a supply point are constrained to on farm storages, irrigation demands and maximum extraction rate at supply point. Note other demand types do not have functionality to make requests for off allocation water. Where specified, the on farm storage has an option to fill the storage to maximum storage volume with off allocation water. Each time step the on farm storage will place an additional request to bring the storage to maximum capacity. Depending on configuration settings, each time step the irrigation demand model may request off allocation water to fill rice ponds to maximum pond levels or other crops to opportunistic soil moisture targets (specified as depletions).
The bulk licensing node represents a point in the system where a portfolio of licences are aggregated together and are accounted together. In terms of off allocation water the off allocation requests of users associated with this node are combined together and sent to the associated OAN as a bulk request. The amount of the request that is allocated and delivered is then shared to associated licences according to specified sharing rules. Noting that delivery efficiency is taken into consideration from the bulk licensing node and not the portfolio of licences. The bulk licensing node also provides and optional off allocation use limit.
Storage nodes may optionally specify an unregulated operating target. Each day an off allocation request will be made to bring the storage up to the unregulated operating target. Note this target may be a function.
OANs group together requests from downstream water users and other OANs and pass these requests on to upstream OANs. These requests may optionally be capped to an upper limit. This functionality is provided to share different sized events amongst multiple downstream reaches. For example small events may only be shared to the most upstream reaches and very large events might be shared with all downstream reaches.
When off allocation reaches a water user the water may be used for three purposes, in the following priority order:
avoiding shortfalls in meeting the current regulated requirement
offsetting use debit orders
supplying water user node opportunistic requirements of crops and filling on farm storages
Off-allocation flow event triggers and volume estimation
In general, off-allocation events are triggered when flows at a location exceed a set of conditions, but these may also be subject to constraints when extraction of flows will result in some other conditions not being met. For example, the following types of off-allocation flow access conditions exist across New South Wales valleys:
river operators judging when flows exceed regulated and essential requirements (operator triggers)
exceedance thresholds
water account triggers
storage volume triggers
water quality constraints
environmental constraints
duration and time of year triggers
Flow event triggers are based on flows exceeding flow thresholds at an OAN. These thresholds may be fixed numbers or a function and different thresholds can be specified for commencing and ending the off allocation event. The event triggers may be optionally constrained by a seasonal period and a maximum flow threshold, which may be a fixed number or function. The threshold can be configured to be based on total flow (Figure 1) or flow above orders (Figure 2). In the case where triggers are based on flow, the larger of orders and event trigger is adopted as the threshold. The off allocation volume may be determined as flow above threshold (Option 2 and 3 in respective Figures 1 and 2) or flow above orders (Option 1 and 4 in respective Figures 1 and 2).
Note the thresholds are based on flow and consequently do not take ownership into consideration. This is dealt with when water is shared to downstream users. The off allocation volume is split according to the share of each owner above regulated requirements. Then shared to downstream water users according to sharing rules for the OAN in the OAS associated with the owned share of the off allocation volume.
Figure 1. Off-allocation thresholds based on total flow |
Figure 2. Off-allocation thresholds based on orders |
Off-allocation system components
As stated in Overview, an off-allocation flow sharing system is described by:
Resource assessment system (RAS), which it may inherit ownership from
An off-allocation system, which is an accounting type within the RAS
Off-allocation node (OAN), which contains the water users that send requests for off allocation water
Accounts, which are the resource shares and associated usage of account holders/water users associated with the OAN
Figure 3 shows the relationships between the major components of an off-allocation system in a Source model.
Figure 3. Components of an off-allocation system
For each RAS there can only be one OAS, each OAS can have one to many account types (there will be one account type for each OAN created in the scenario). An OAN can only have one account type per RAS but may have other account types as part of other RAS / OAS's (this allows for a single OAN to be used to model off-allocation flows for multiple owners at a single point in the river). For each account type there can be zero to many accounts, but each account has one account holder.
An account holder can be any of the following types of nodes downstream of the OAN which have a demand for off-allocation water:
Water User Node,
Bulk Licensing Node,
Environmental Demand Node,
Storage Node or
Off-Allocation Node
The OAS is defined at three different levels:
system wide properties are defined at the off-allocation system level,
properties of each OAN are defined at the account type level, and
individual node/user settings are defined at the account level.
Note that although Ownership is not configured directly for an off-allocation system, off-allocation flow sharing is always used in conjunction with a resource assessment system. When off-allocation sharing is configured for a scenario, it must be linked to an associated resource assessment system by the modeller. If ownership has been configured for the linked resource assessment system then that owner’s share of flow at the OAN is subject to owner shares of the off allocation volume.
Methodology
Variables Used
Variables used are listed in Table2, excluding some temporary variables used locally in some equations; these are defined where they are used.
Table 2 — List of Variables Used
Symbol | Purpose/Description | Units | Usage |
|---|---|---|---|
a | A water user account at the OAN. | n/a | Initialisation, Flow |
AccessRatio(a,owner) | Ratio of allocation to request volume for an account (representing a water user and owner). Indicates whether there is an excess to reallocate to other owners and/or water users. | n/a | Flow |
Allocated | Total volume allocated to all accounts at the current priority level, p. | volume | Flow |
Allocation(a) | The volume of water allocated to an account | volume | Flow |
Balance(a,t) | Balance of a water user account in a time step, t. This is the volume of off-allocation water assigned to the associated water user and owner that is expected to arrive at the water user's location (e.g. Supply Point Node) in the time step. | volume | Flow |
Cap(a) | Account cap for an account a – representing the maximum usage permitted for the account in the water year. | volume | Flow |
Cap(type) | Cap at the OAN represented by the account type, type, representing the maximum off-allocation usage permitted at the OAN in the water year. | volume | Flow |
Cap(system) | Cap for an off-allocation system, system , representing the maximum usage permitted for the off-allocation system in the water year. | volume | Flow |
DeliveryEff(a) | Factor that represents the efficiency of delivery of water requested using water user account a. | n/a | Flow |
Excess | Total volume allocated that is in excess of the system cap | volume | Flow |
Flow | The volume of flow in the river at the OAN for the current time step | volume | Flow |
InitialUsage(a) | The initial usage figure set by the user for the account a. | volume | Initialisation, Flow |
LimitUsage(a) | Maximum remaining usage for the water user account a in the current time step. This may be the total remaining request. If the account's usage is capped, the remaining usage will be limited by the remaining usage under the cap. | volume | Flow |
LimitUsage(system) | The maximum volume of water left to be allocated to accounts in the OAN's system in the current water year. This limitation only applies to systems with a usage cap. | volume | Flow |
Loss(wu, owner | An owner's share of the estimated volume of loss that will be incurred in delivering a water user's request leaving the OAN this time step. | volume | Flow |
MaxQ | Maximum flow threshold, used for defining off-allocation events (see Figures 1 and 2) | volume | Flow |
MinRatio | Minimum usage ratio for all OAN accounts at the current priority level. | n/a | Flow |
NextRatio | Next lowest usage ratio after the minimum for all accounts at the current priority level | n/a | Flow |
OrderDue | Total volume of order due at the OAN in the current time step. | volume | Flow |
OrderDue(owner) | Volume of order due at the OAN in the current time step for owner. | volume | Flow |
OrigRequest(a) | The saved value of Request(a) before the allocation process begins. | volume | Flow |
OrigRequest(a, owner) | The saved value of Request(a, owner) before the allocation process begins. | volume | Flow |
owner |