Note: This is documentation for version 4.11 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. |
Equalise Access Opportunity | For reaches down stream of a given point of tributary inflow, the equalise access opportunity principle is to ensure that water made available for off-allocation flow extraction is shared equitably between users within a priority group. Sharing may be based on supplementary entitlement or installed pump capacity. |
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,
- 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 | A water owner at the OAN | n/a | Configuration, Flow |
other | A different water owner to owner at the OAN | n/a | Flow |
p | The current priority level | n/a | Flow |
Proportion | Proportion by which allocations at the current priority level in the current time step need to be reduced so that they fit within the system cap. | n/a | Flow |
RatioOffAlloc(owner) | An owner's share of the total off-allocation volume remaining to be allocated this time step at the OAN. | n/a | Flow |
Request(a) | The volume of off-allocation request placed for account a of water user wu up-scaled for loss to the total required at the OAN. | volume | Flow |
Request(a,owner) | The volume of off-allocation request placed for a water user and owner up-scaled for loss to the total required at the OAN. | volume | Flow |
RequestAtSource(a) | The volume of off-allocation request placed for account a of water user wu at its location (e.g. at a Supply Point Node). | volume | Flow |
ReserveProp(type) | Configured proportion of off-allocation flow reserved (not available for allocation) at the OAN (represented by account type type ) | n/a | Configuration, Flow |
sa | A water user account in a given off-allocation system | n/a | Flow |
ShareVolume(a) | The volume of off-allocation water to be shared to account a in the current time step. | Flow | |
ShareVolumeAtSource(a) | The volume of off-allocation water to be shared to account a in the current time step, reduced for delivery efficiency so that it is the amount available at the water user's location (e.g. at a Supply Point Node). | volume | Flow |
system | An off-allocation system | n/a | Configuration, Initialisation, Flow |
t | Index of the current time step | n/a | Flow |
tdelivery(a) | Estimated number of time steps to deliver water from the OAN to the water user's supply point for account a . | n/a | Flow |
type | The account type which represents the OAN in the off-allocation system. | n/a | Flow |
TotalUnitShare(p) | The total number of specified unit shares for all OAN accounts at a priority level p . | n/a | Configuration, Flow |
UnitShare(a) | The number of specified unit shares for a water user's account a at the OAN. | n/a | Configuration, Flow |
Usage(a) | The usage to date (in the water year) for a water user account which includes undelivered off-allocation water. This value is reset at the start of a water year. | volume | Flow |
UsageRatio(a) | The usage to shares ratio for an account a - this is used to equalise allocations between accounts at the same priority level. | n/a | Flow |
VolOffAlloc | Total volume of off-allocation water at the OAN remaining to be distributed in the current time step. | volume | Flow |
VolOffAlloc(owner) | Volume of an owner's off-allocation water at the OAN remaining to be distributed in the current time step. | volume | Flow |
wu | A water user with an account at the off-allocation node. | n/a | Configuration, Initialisation, Flow |
Initialisation Phase
The account type usage is set to the initial usage value.
- The total usage for all the accounts associated with each OAN is initialised by adding the initial account usage volumes as defined by the modeller (Note: If the account holder is a downstream OAN then the initial usage for the account type is the sum of all water users which have accounts at that OAN account type.)
For each account a at the OAN (i.e. of its account type):Initialise usage for the account:
If usage at the OAN is capped, the account is assigned its share of the usage cap, and the remaining balance to be used is determined:
The system's usage limit (usage remaining under system cap level) is initialised:
If a system cap limit has been specified by the modeller, the remaining system cap is set, based on the cap and usages:
Flow Phase
During the flow phase, when an OAN is reached the off allocation sharing process is undertaken. The process is illustrated in Figure 4. The first step in the process is to check if accounts need to be reset and the second step is to determine the off allocation volume to share. Finally if there is off allocation volume to share this volume is shared to users according to shares and account type sharing rules. Initially the volume is constrained to the system and account type cap. If volume still remains the appropriate sharing threshold and associated priorities are determined. Noting that if the first threshold is not reached then no sharing occurs. Users’ shares are then constrained to their remaining cap. Starting at the highest priority users first, signified by the lowest priority number, group these users together for sharing. If equalise access opportunity has been specified then users with less access share are brought up to the next highest access share. This is repeated until all access shares are equalised or no more off allocation volume remains. Any remain volume is then shared to water users according to their shares. If there is any remaining off allocation and there are more priority levels then the process moves to the next priority level and repeats the process until there is no more off allocation volume of all the users in all priority levels have been satisfied.
Note in the sharing process there may be a distinction between the requests that reach the OAN (target requests) and the requests made at each water user node (source requests). The ratio of these two is known as the delivery efficiency. A number greater than 1 signifies water will be lost and less than 1 that water will be gained, noting the former is more common. It is also possible to override this number with a modeller specified delivery efficiency. The allocation is based on target requests and accounting is based on source requests and account constraints. Consequently the delivery ratio is used to transfer between water that is allocated and water that is accounted at the OAN.
In the case of ownership the off allocation sharing process is repeated for each owner based on the owners share of the off allocation volume.
Figure 4. Flow phase process diagram
The following steps are performed at each time step at each off-allocation node during the flow phase.
Reset Account Balances
- Check if the current time step is the start of the water year. If so the usage for each account at the OAN is set to zero.
- If the usage is reset on spill then check if the specified storage(s) are spilling. If the specified storage(s) are spilling:
- If reset when first spill - the usage for each account at the OAN is reset to zero only if the storage(s) were not spilling at the previous time step.
- If continuously reset on spill - the usage for each account at the OAN is reset to zero at any time step where there is a spill.
Allowing for estimated travel time to each downstream water user of the types listed previously, the balance of the associated account a is set to zero at a future time step.
Determine if there is an off-allocation event
This is based on the off-allocation event conditions being met in the current time step.
- If seasonal start and end dates have been specified by the modeller, a check is made to determine whether the current time step is between the specified start and end dates; if it is between the specified dates then it is in an off-allocation period.
- Whether the flow at the OAN has exceeded the relevant flow threshold is then checked. If the modeller has specified a different threshold for the start and the end of the event, the starting threshold is only used in the initial time step for the event (e.g. the first day); for subsequent time steps the end threshold is used when determining if in an off-allocation event continues. The modeller will also have defined if the threshold relates to the total flow (see Figure 1) or the flow above orders (see Figure 2). If the modeller has also specified a maximum flow threshold then this is checked at the same time; off-allocation flow is only available when flow is above the lower limit threshold and below the maximum flow threshold (if a maximum flow threshold is specified).
Determine the off-allocation volume
If an off allocation event is triggered then the volume of off-allocation flow for the current model time step (VolOffAlloc) is determined at the OAN by the following steps; recalling that the modeller has the option to specify that the calculation of off-allocation volume at the OAN is based on one of the four options illustrated in Figures 1 and 2.
- The off-allocation volume is calculated according to the selected option:
Option 1 (flow exceeds a threshold, all water above regulated requirements is available):
Option 2 (flow exceeds a threshold, all water above the maximum of the regulated requirements and threshold is available)
Option 3 (flow exceeds regulated requirements plus threshold (ΔQ) and all flow above regulated requirements plus ΔQ is available)
- Option 4 (flow exceeds regulated requirements plus threshold (ΔQ), all flow above regulated requirements is available):
If VolOffAlloc = 0 then processing for this OAN ends.
If a proportion of the off-allocation volume is specified to be held in reserve (as defined for the off-allocation node's account type) then the available volume of off-allocation flow is reduced in line with that proportion:
If ownership is assigned to the off-allocation volume:
Resource Allocation
Requests for off-allocation water are generated during the Order Phase. Requests are placed by each water user, indicating their requirements for off-allocation water. How these requests are generated by the different water users has been previously discussed (see section on off allocation requests). When ownership is enabled, an identical request is made for each owner associated with the water user. This is done to maximise access to off-allocation water to all owned water.
By the time a request reaches the off-allocation node, it will be a different volume to the original request as it will have been adjusted (increased) for losses. When ownership is enabled, these losses may differ between owners, according to the modeller's configuration of loss attribution to different owners.
The off-allocation node (OAN) distributes water available between accounts according to their share of requested water. The amount distributed to each account may be limited by an account cap and a user limit, and can also be limited by a system cap. It also cannot exceed the volume requested by the associated water user via a supply point, downstream OAN, bulk licensing, environmental demand or storage node. The balance of an off-allocation account is therefore referred to as its 'usage', as all water in this category of account must be requested before it is assigned.
When ownership is enabled, too much water is likely to be distributed as the request is duplicated for each owner. It is possible for one account at a node to have excess water and for others to have insufficient, as there may be more of the associated owners' water in the river, or owner accounts can have different caps. Where this occurs, an owner's off-allocation water in excess of their request or cap may be assigned to other owner's accounts at the same water user. Any excess off-allocation water that remains is then re-assigned to other water users.
The following steps are performed at each OAN to calculate the off-allocation volume and allocate it to accounts.
Save each owner's request for off-allocation water (the volume at the OAN; i.e. adjusted for losses).
- If ownership is enabled and there is more than one owner, the owner loss contribution, Loss(wu, owner), in meeting the request for each water user at the OAN, are determined. Determine the loss contribution of each owner describes how this is done.
- The volume of off-allocation water that is available, VolOffAlloc , is calculated. See Determine the off-allocation volume below for details.
- The off-allocation water is allocated. If ownership is not enabled or there is only one owner, the steps below are only performed once. When there are multiple owners, they are repeated until either there is no off-allocation water to share, or all requests are met, or the system's usage limit has been reached (if there is such a limit).
A check is made to see whether there is any off-allocation water to allocate, or not. If there is no off-allocation water (remaining) to share (ie. if VolOffAlloc = 0 or VolOffAlloc < lowest volume allocation level ), the allocation procedure stops here.
How much of the total requested volume at the OAN can be met/supplied is determined.
If met ≤ 0 , the allocation procedure stops here.
If there is a usage cap defined for the off-allocation system, a check is made to see if there is remaining usage capacity. This is calculated based on the current usages of all accounts a at every OAN in the off-allocation system:
If LimitUsage(system) = 0 , there is no remaining system cap to share, so the allocation procedure stops here.
The off-allocation delivery efficiency is determined for each account using the following equation:
where a is the account for a downstream water user. (Recall that each water user which requires off-allocation flow to be allocated to them from a particular OAN in the river system holds one off-allocation account at that node.)- Determine the maximum volume of a request remaining to be fulfilled for each off-allocation account a at downstream water users:
If there is a usage cap configured, it is the smaller of the request and the remaining usage cap
- Otherwise, it is the requested volume
- If no account has LimitUsage(a) > 0 , the allocation procedure stops here.
- Off-allocation water is allocated to accounts at the OAN. At every priority level, in order from highest to lowest, the following occurs:
- If the equalise shares option has been selected, account allocations/usages at a given priority level are equalised based on their usage to shares ratio. Equalise shares of off-allocation water describes how this is done.
- Remaining off-allocation water is allocated to accounts at the given priority level according to account shares. Allocate off-allocation water to accounts based on shares describes how this is done.
- If the equalise shares option has been selected, account allocations/usages at a given priority level are equalised based on their usage to shares ratio. Equalise shares of off-allocation water describes how this is done.
At this stage the OAN may have met each of the water user's owner requests and thus supplied more water than the water user requires – as the total request was placed for every owner. The steps that follow check for this and re-distribute any excess allocation – firstly to other water users of the same ownership, then to other water users. The process depends on how many owners there are:
If ownership is disabled or there is only one owner, usage is simply updated:
Otherwise (i.e. there is more than one owner):- Any excess is redistributed according to the method described in Re-distribute off-allocation excess.
- The usage for this round of allocation is updated
- Return to step 3. The next round will redistribute any losses met by other owners to water user accounts with insufficient water to meet requests.
- Any excess is redistributed according to the method described in Re-distribute off-allocation excess.
Account balances for every account at the OAN are updated
Determine the loss contribution of each owner
Every owner at a water user is assigned the same volume of opportunistic requests from downstream water users – this is so any additional water can be used to fulfil the request as it becomes available, regardless of ownership. Losses are incurred between the water user's location and the OAN. The total loss is added on to every owner's request. When the water is allocated at the OAN to owner accounts to meet the request, each owner's allocated volume needs to be adjusted for losses met by other owners. In order to do this, it is necessary to have established the owner's 'loss contribution' – i.e. their share of the loss.
This is done either by:
- Keeping track of the owner's share of the loss volume for each owner request – i.e. adding on their loss at every node and link between the OAN and the water user the request originates from
or
Using a matrix to solve the owner's share:
Equalise shares of off-allocation water
This is an optional process that is undertaken only if the modeller specifies that it should be done. The following steps are repeated until either there is no more off-allocation water to assign, or the lowest account usage to share ratios are equal (see step 3).
For a given priority level of accounts, the usage to shares ratio for every OAN account at the current priority level is calculated:
The two accounts at this priority level with the lowest ratios are found
- Check to see whether the two lowest ratios are the same:
- If this is the case (MinRatio = NextRatio), the equalised allocation process is finished – exit this priority level and move on to the next one.
- Otherwise continue on.
- If this is the case (MinRatio = NextRatio), the equalised allocation process is finished – exit this priority level and move on to the next one.
- For each account a at the current priority level, the following occurs:
- If VolOffAlloc = 0 then equalisation ends.
- If the account request/usage limit has been reached (LimitUsage(a) = 0), this account is skipped and processing of the next one starts.
The volume required to bring the ratio of the current account up to the second lowest accounts ratio is calculated:
Water is allocated to the account and limits are updated
Reduce the volume of off-allocation water available to share
- If VolOffAlloc = 0 then equalisation ends.
- Return to step 1 to continue equalisation.
Allocate off-allocation water to accounts based on shares
Firstly, at the current priority level, p :
Then for each account a, at the current priority level p , off-allocation water is allocated to accounts via the following steps:
Limit the share volume for an account (Note that if LimitUsage(a) is not specified by the modeller its value defaults to a very big number):
- Reduce the volume of off-allocation water available to share
- Calculate the volume that this represents at the source
Calculate allocations for the account for each user and adjust the usage limits if required.
- If a system cap has been specified and would be exceeded by allocations in the current time step, then allocations are reduced to fit within cap (otherwise this step is skipped).
Sum the allocations for each user in the current priority level
Calculate the volume by which the system cap would be exceeded based on potential allocations
Calculate the proportion that each allocation would have to be reduced by to meet the system cap restriction
For each OAS node account at the current priority level allocations are adjusted so that they do not exceed the system cap, taking into account the efficiency factors, then the limits for the adjustment are updated:
Re-distribute off-allocation excess
When there are multiple owners, excess water may have been allocated as the water user's requested volume was duplicated for each owner. This method redistributes the excess, then determines the new excess volume for each owner once losses met by other owners at all water users are taken into account.
The excess off-allocation volume available for re-distribution is initialised:
- For each water user, excess off-allocation water is redistributed:
The access ratio for each off-allocation account and the total of these account ratios for each water user are determined,
where a is the account for water user and owner owner.- The access ratio is checked to determine whether water in excess of the total request has been allocated:
If AccessRatio ≤ 1 , there is no excess to redistribute. The remaining request to be met is calculated as:
Skip to the next water user.- Otherwise processing continues in order to redistribute excess between owner accounts.
Assuming that a water user will try and maximise its access to off allocation water, Source uses each owner's off-allocation water on the basis of its allocation (an indication of licence priority), or its remaining capacity to receive water if accounts are capped. The account with the largest allocation has this adjusted first until it is the same as the next largest, and so on. This cycle is repeated until all the excess off allocation water is allocated or accounts have no remaining capacity to receive water. - The new allocation for each water user's off-allocation account is initialised:
If accounts are capped:
Otherwise
where a is the account for water user and owner owner.
- The owner accounts for each water user are ranked in order of allocation, newAlloc(owner), from highest to lowest.
Excess is allocated to owners in the ranked order until the total remaining request volume is met, but the allocation is equalised so that lower priority owners also get some water – the result is a new 'equalised' allocation, newAlloc(owner).
remvol= Requestwu do i= 2, nowner sum= 0 do j= 1, i-1 sum= sum +rembal(ptr(j)) end do vol= min(remvol,sum-rembal(ptr(j)*(i-1)) do j= 1, i-1 rembal(ptr(j))= rembal(ptr(j))-vol/(i-1) end do remvol= remvol - vol If( remvol <= 0 ) exit end do if( remvol > 0 ) then sum = 0 do j= 1, nowner sum= sum + rembal(ptr(j)) end do vol= min(remvol,sum) do j= 1, nowner rembal(ptr(j))=rembal(ptr(j))-vol/nowner end do remvol= remvol- vol end if
The allocation for this time step is updated for the re-distribution:
The remaining volume of off-allocation water not required by this water user is added to the total to be reallocated to other water users:
The off-allocation volumes are adjusted for losses met by other owners:
Every owner's ratio of the total off-allocation volume is calculated:
The loss met by every other owner is their loss volume (calculated in Step 2 under Flow Phase (Resource Assessment and Allocation)) multiplied by their share of the off-allocation volume. This means that for a given owner, the off-allocation volume adjusted for other owner losses is:
Indicate that the water user's request has been met:
Request(a,owner) = 0
Examples
Opportunistic requests in parallel systems
Figure 5 below shows two examples of where a water user node can be supplied from multiple off allocation nodes. The first is by passing requests up both branches of a confluence and the other are off allocation in separate river reaches.
Figure 5. Examples of a water user node being supplied from multiple off allocation nodes
In both of these situations the total opportunistic request is passed to both off allocation nodes. The off allocation node that is processed first, attempts to allocate the full requirement. Any remaining off allocation requirement may be met by the second off allocation node.
If there are different travel times between the off allocation nodes and the supply points, the furthest off allocation node will be processed first. The allocation is made to the user's account for the required delivery time step. When the second off allocation node is processed, allocations are made with respect to the same delivery time step.
If the travel times are the same, the order in which nodes are processed is based on rules specified by the modeller.
Sharing between off allocation reaches
Each OAN processes the orders for its direct users downstream (including the next downstream OAN) and passes the combined orders up to the next OAN (if there is one). This means that it is possible to share off allocation water between multiple downstream reaches.
In the example illustrated in Figure 6, below, OAN3 has a share component in OAN2 which also has a share component in OAN1. This means that the off-allocation requirements of water user 3 and 4 are accumulated up the system and are reported as the off-allocation requirement of OAN2. This means that the allocation of off-allocation water to reach 1 takes into consideration the downstream requirements. It is possible to give priority access to downstream requirements by assigning the highest priority to OAN2 in the OAN1 allocation table.
Note that while OAN1 assigns a volume of off-allocation water to OAN2, the processing of OAN2 may result in a change in the volume of off-allocation water available to that reach as the rules specific to OAN2 are used to calculate the available water.
Figure 6 — Example of multiple off allocation reaches
Off allocation and storages
It is assumed that any storage which is downstream of an OAN is a re-regulating storage. The modeller can define an opportunistic target volume for such storages. All users, including re-regulating storages, have equal priority access to any off-allocation water by default; however, the modeller can customise the priority rules through the volume allocation table.
Defining Complex Rules for Event Triggers
In practice, complex rules can be used to define off-allocation events. These can be replicated in Source through use of the function editor to define event triggers. Some example rules which can be replicated using the function editor are as follows:
Flow thresholds at multiple gauge nodes: the function would check that the required flow threshold at all these was exceeded at the previous time step.
Water Account/Allocation Triggers - In some systems, off allocation event declaration depends on the volume in user accounts. This can be replicated using the function editor by referring to the total account type balance, for example for general security accounts.
Storage Volume Triggers - Off-allocation flow events will be triggered only if flows cannot be regulated through downstream storages. This can occur for storages in the current off-allocation reach or in downstream off-allocation reaches. If only the current reach needs to be considered, then the event trigger does not need to account for the available storage airspace. This is because the re-regulating storage is given priority in the allocation of off-allocation water. If, however, storages in downstream reaches are to be considered, then the trigger will have to use an function to evaluate the available airspace in the storages at the previous time step. A threshold is returned such that the volume required to fill the storages in the downstream off-allocation reaches is not made available to the current reach.
Water Quality Conditions -In some cases the declaration of an off-allocation flow sharing event may be dependent on water quality conditions prevailing at the time. To model this in Source the function editor can be used to compare the relevant water quality value at the previous time step with a modeller specified reference value. If the water quality condition is satisfied then the corresponding flow value is used as the basis of a threshold (as per Figures 1 and 2) for determining off-allocation.
Environmental Conditions - The declaration of an off-allocation flow event may be dependent upon whether the taking of water will prevent the beneficial watering of an environmental value or asset. This can be replicated by developing a water user with an environmental demand model. The highest allocation priority should be assigned to the associated Supply Point. It should be noted that if this Supply Point is in a downstream off-allocation reach, the downstream OAN would have to be assigned highest priority when evaluating the current off-allocation reach. This also means that other off-allocation demands in the downstream reach, such as for irrigation, would get highest priority, which may not be desirable.
Data
Input data
Details on input data are provided in the Source User Guide.
Parameters or settings
Off-allocation System Parameters
Parameters input by the modeller at the system level apply across all OANs and account types created within the off-allocation system (OAS).
Table 3 — Off-allocation System Configuration - Parameters
Parameter Name | Parameter Description | Unit Type | Allowable values & validation rules | Default Value(s) |
---|---|---|---|---|
Owner | Display only, the owner associated with the resource assessment system | n/a | n/a | n/a |
Water year start date | Display only, day and month the water year starts as configured in the associated RAS | n/a | n/a | n/a |
Equalise shares | If the equalise shares option is selected, allocation of off-allocation flow is equalised across all users within a priority level | Boolean | Optional | False |
Annual System Cap activation | A check box to activate an annual system cap | Boolean | Optional | False |
Annual System Cap | A volumetric cap on usage for the OAS. | Volume | If annual system cap is activated | 0 |
Sum of Account Type Caps | Sum of account type caps as a proportion of the annual system cap | Percent | If annual system cap is activated | 0 |
Reset on Spill | An option which is used in conjunction with a storage/s in the scenario, when a selected storage spills in a time step the usages for all accounts (for all account types) across the off-allocation system are reset to zero | Boolean | Optional | False |
Spill Trigger | Specifies whether balances are reset on the first spill of a event or on every spill | Option | If reset on spill is activated | First spill |
Storage Trigger | Specifies whether all select storages or any selected storage is considered | Option | If reset on spill is activated | Any Storage |
Assigned storages | Displays a list of storages in the system to choose from | Option | If reset on spill is activated | False for all storages |
Assigned storages | Not sure why have this twice? |
Off-allocation Account Type Parameters
Parameters input by the modeller at the account type level affect all associated accounts.
Table 4 —Account Type Configuration - Parameters
Parameter Name | Parameter Description | Unit Type | Allowable values & validation rules | Default Value(s) |
---|---|---|---|---|
Off allocation | The off allocation reach that the account type is associated with | none | Mandatory | First off allocation node without an account type |
Annual Usage Limit activation | A check box to activate an annual usage limit | Boolean | Optional | False |
Annual Usage Limit | The annual usage limit for the account type | If the annual usage limit is activated | 0 |
Table 5 — Volume Allocation Table – Parameters
Parameter Name | Parameter Description | Unit Type | Allowable values & validation rules | Default Value(s) |
Off-allocation Volume | The volume of off-allocation flow at the node for which allocation priority is defined. | Volume | Real ≥ 0 | 0 |
Account Priorities | The priority each downstream water user has in the system for each allocation volume as defined by the user | n/a | 1….n* | 1..n |
User | Displays each downstream user account against which a priority must be assigned for each allocation volume level entered | n/a | Users displayed must include all accounts from Table 6. | none |
Parameters for Off-allocation Accounts
Account Type Accounts Table – Parameters
Parameter Name | Parameter Description | Units | Allowable values & validation rules | Default Value(s) |
---|---|---|---|---|
Name | Name of the water user node. | N/A | Name of an existing downstream supply point, environmental demand, storage, or OAN | None – read only as per node name |
Type | The node type | N/A | Supply Point, Environmental Demand, Storage and Off-Allocation node | None – read only – as per node type |
No. of Shares | The number of unit shares associated with a water user | N/A | Integer ≥ 0 | 1 |
Initial Usage | Starting volume of used off-allocation flow for the water user's account | Volume | Mandatory | 0 |
Use User Limit | Checkbox to enable the configuration of the user limit | N/A | True/false | False |
User Limit | A fixed value or function that defines the user limit | Volume | Real ≥ 0 | 0 |
Table 6 — Off Allocation Node – Parameters
Parameter Name | Parameter Description | Unit Type | Allowable values & validation rules | Default Value(s) |
---|---|---|---|---|
Trigger Method | A choice between total flow or flow above regulated requirements | Option | Radio button options for 'Total Flow' and 'Flow above regulated requirements' | Total Flow |
Volume Calculation Method | A choice between flow above threshold and flow above regulated requirements | Option | Radio button options for 'Flow above threshold' and 'Flow above regulated requirements' | Flow above threshold |
Start flow | Flow threshold to signal off allocation on the first time step of an event | Flow | Can be specified as a fixed value or a function | 0 |
End flow activation | A check box to activate the end flow threshold | Boolean | Optional | False |
End flow | Flow threshold to signal off allocation after the first time step of an event | Flow | If end flow is activated | 0 |
Maximum flow activation | A check box to activate the maximum flow threshold | Boolean | Optional | False |
Maximum flow | A flow threshold above which off allocation is not available | Flow | If maximum flow is activated | 0 |
Reserve Proportion | The proportion of off-allocation flow which cannot be allocated | Percent | Mandatory | 0 |
Threshold seasonal event | A check box to activate the event season | Boolean | Optional | False |
Season Start | Specifies the start date for the time period when the off-allocation flow event may occur | dd-mmm | If threshold seasonal event is activated | 01 Jan |
Season End | Specifies the end date for the time period when the off-allocation flow event may occur | dd-mmm | If threshold seasonal event is activated | 31 Dec |
Max Upstream Request activation | A check box to activate the Max upstream request | Boolean | Optional | False |
Max Upstream request | I assume this limits the request sent from the OAN to the next OAN | Flow | If the max upstream request is activated | 0 |
Output data
Table 7 — Recorded variables
Model Element | Parameter | Frequency | Notes |
---|---|---|---|
Off-allocation system | Remaining Capacity: Difference between system cap and system usage | time step | For each off- allocation system configured |
Off-allocation system | Usage: System usage | time step | For each off- allocation system configured |
Account Type | Remaining Capacity: Difference between account type cap and account type usage | time step | For each off- allocation system account type configured |
Account Type | Usage: Account type usage | time step | For each off- allocation system account type configured |
Accounts | Remaining Capacity: Difference between account limit and account usage | time step | For each account in an off- allocation system account type |
Accounts | Usage: Account usage | time step | For each account in an off- allocation system account type |
Water user/Account Holder | Allocation: No sure? | time step | For each account holder in an off- allocation system account type |
Water user/Account Holder | Constrained Order: Don't know? | time step | For each account holder in an off- allocation system account type |
Water user/Account Holder | Equalisation Ratio: Ratio between water user usage and total usage for the account type | time step | For each account holder in an off- allocation system account type |
Water user/Account Holder | Non Debit Balance: Don't know | time step | For each account holder in an off- allocation system account type |
Water user/Account Holder | Order Volume: Off allocation request volume for the current time step | time step | For each account holder in an off- allocation system account type |
Water user/Account Holder | Remaining Capacity: Difference between the water user off allocation limit and the water user usage | time step | For each account holder in an off- allocation system account type |
Water user/Account Holder | Total Volumetric Share: Off allocation share since the start of the water season | time step | For each account holder in an off- allocation system account type |
Water user/Account Holder | Usage: Accumulated off allocation use since the start of the water year | time step | For each account holder in an off- allocation system account type |
Water user/Account Holder | Usage Today: Off allocation volume used in the current time step | time step | For each account holder in an off- allocation system account type |
Water user/Account Holder | Volumetric Share: Share of off allocation volume | time step | For each account holder in an off- allocation system account type |
Off-allocation node | Borrow and Payback | time step | For all off allocation nodes |
Off-allocation node | Constituents | time step | For all off allocation nodes |
Off-allocation node | Downstream flow>Flow: Downstream flow | time step | For all off allocation nodes |
Off-allocation node | Downstream flow volume>Volume: Downstream volume | time step | For all off allocation nodes |
Off-allocation node | Mass balance | time step | For all off allocation nodes |
Off-allocation node | Off allocation Flow Volume>Volume: Volume of off allocation | time step | For all off allocation nodes |
Off-allocation node | Off Allocation Orders Volume | time step | For all off allocation nodes |
Off-allocation node | Ordering Network | time step | For all off allocation nodes |
Off-allocation node | Rules Based Orders | time step | For all off allocation nodes |
Off-allocation node | Storage Volume | time step | For all off allocation nodes |
Off-allocation node | Total Inflow Volume | time step | For all off allocation nodes |
Off-allocation node | Total Outflow Volume | time step | For all off allocation nodes |
Off-allocation node | Upstream flow>Flow: Upstream flow | time step | For all off allocation nodes |
Off-allocation node | Upstream flow volume>Volume: Upstream volume | time step | For all off allocation nodes |