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 2^nd 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. For each OAN in the system the modeller specifies an off-allocation 'account type', where the account type contains all the off-allocation accounts for all the water users who can be allocated off-allocation water from that 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. An off-allocation account may also be allocated a priority at an OAN based on a defined volume of off-allocation water.
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. A storage can generate an off-allocation request with the aim of bringing it to full supply volume or up to its unregulated target.
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. By default this value is set to 0 (i.e. all off-allocation flow can be allocated) If a non-zero value is entered then once the volume of off–allocation flow at an OAN has been calculated it will be reduced by this reserve 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 Loss(wu, other)	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 Each account at the OAN represents a downstream water user's supplementary entitlement to each owner's off-allocation flow at the node. These accounts are assigned a priority level by the modeller – which effectively prioritises the access of the downstream water user to off-allocation water. The lowest number has the highest priority.	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
Ratio_OffAlloc(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) Usage(sa)	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
Vol_OffAlloc	Total volume of off-allocation water at the OAN remaining to be distributed in the current time step.	volume	Flow
Vol_OffAlloc(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. Note: recall the definition of "water user" in the list of Definitions. We have to be a little careful here. I couldn't find my comment on being the same thing, but the main difference from a coding point of view between an account a and a water user wu, is that a water user isn't ever an account of an off allocation account type. The supply point is the account. What this means is that a water user can be associated with many accounts. This has ramifications for the way water is allocated to an account. As an example if a water user is attached to 2 supply points, then it will send the same request up both branches of the system. This means that we have to make sure this request is not over fulfilled, so when the off allocation node goes to distribute off allocation allocations to users, it first checks that any requests from associated water users to the account have not already been fulfilled by accounts on other off allocation nodes. Realise this is confusing, so happy to sit down and talk you through it. Generally speaking I think we need to be careful how we use these terms and make sure we only use primarily 1 (prob 'a') unless necessary.	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):
1. Initialise usage for the account:
2. 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:
1. 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:
1. 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.
2. 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.
Note: if no storage is specified then the usage is not reset based on this criterion.
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 (Vol_OffAlloc) 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 Vol_OffAlloc = 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, Vol_OffAlloc ,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).
1. 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 Vol_OffAlloc = 0 or Vol_OffAlloc < lowest volume allocation level ), the allocation procedure stops here.
2. How much of the total requested volume at the OAN can be met/supplied is determined.
  
  If met ≤ 0 , the allocation procedure stops here.
3. 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.
4. 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.)
5. Determine the maximum volume of a request remaining to be fulfilled for each off-allocation account a at downstream water users:
  1. If there is a usage cap configured, it is the smaller of the request and the remaining usage cap
  2. Otherwise, it is the requested volume
  3. If no account has LimitUsage(a) > 0 , the allocation procedure stops here.
6. Off-allocation water is allocated to accounts at the OAN. At every priority level, in order from highest to lowest, the following occurs:
  1. 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.
  2. 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.
7. 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):
  1. Any excess is redistributed according to the method described in Re-distribute off-allocation excess.
  2. The usage for this round of allocation is updated
  3. 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.
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:
1. If this is the case (MinRatio = NextRatio), the equalised allocation process is finished – exit this priority level and move on to the next one.
2. Otherwise continue on.
For each account a at the current priority level, the following occurs:
1. If Vol_OffAlloc = 0 then equalisation ends.
2. If the account request/usage limit has been reached (LimitUsage(a) = 0), this account is skipped and processing of the next one starts.
3. The volume required to bring the ratio of the current account up to the second lowest accounts ratio is calculated:
4. Water is allocated to the account and limits are updated
5. Reduce the volume of off-allocation water available to share
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).
1. Sum the allocations for each user in the current priority level
2. Calculate the volume by which the system cap would be exceeded based on potential allocations
3. Calculate the proportion that each allocation would have to be reduced by to meet the system cap restriction
4. 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:
1. 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.
2. The access ratio is checked to determine whether water in excess of the total request has been allocated:
  1. If AccessRatio ≤ 1 , there is no excess to redistribute. The remaining request to be met is calculated as:
    
    Skip to the next water user.
  2. Otherwise processing continues in order to redistribute excess between owner accounts.
  Distribution of a water user's excess off-allocation water
  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.
3. The new allocation for each water user's off-allocation account is initialised:
  1. If accounts are capped:
  2. Otherwise
    
    where a is the account for water user and owner owner.
4. The owner accounts for each water user are ranked in order of allocation, newAlloc(owner), from highest to lowest.
5. 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
```
6. The allocation for this time step is updated for the re-distribution:
7. 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:
8. 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 Tick Box option to allow true/false entry	False
Annual System Cap activation	A check box to activate an annual system cap	Boolean	Optional Tick Box option to allow true/false entry	False
Annual System Cap	A volumetric cap on usage for the OAS.	Volume	If annual system cap is activated Real≥0 Cannot be greater than sum of Account Caps	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 Real≥0	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 Tick Box option to allow true/false entry	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 Radio button selection between first spill and every spill	First spill
Storage Trigger	Specifies whether all select storages or any selected storage is considered	Option	If reset on spill is activated Radio button options for 'Any Storage' and 'All Storages'	Any Storage
Assigned storages	Displays a list of storages in the system to choose from	Option	If reset on spill is activated Tick box for each storage in the system	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 Drop down list	First off allocation node without an account type
Annual Usage Limit activation	A check box to activate an annual usage limit	Boolean	Optional Tick Box option to allow true/false entry	False
Annual Usage Limit	The annual usage limit for the account type		If the annual usage limit is activated Real ≥ 0	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* Each user must have a priority defined for each volume level defined.	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 Real ≥ 0	0
Use User Limit	Checkbox to enable the configuration of the user limit	N/A	True/false (If set to false then usage cap is unlimited)	False
User Limit	A fixed value or function that defines the user limit	Volume	Real ≥ 0 Aggregated total of account caps cannot exceed the system cap	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 Real ≥ 0	0
End flow activation	A check box to activate the end flow threshold	Boolean	Optional Tick Box option to allow true/false entry	False
End flow	Flow threshold to signal off allocation after the first time step of an event	Flow	If end flow is activated Can be specified as a fixed value or a function Real ≥ 0	0
Maximum flow activation	A check box to activate the maximum flow threshold	Boolean	Optional Tick Box option to allow true/false entry	False
Maximum flow	A flow threshold above which off allocation is not available	Flow	If maximum flow is activated Can be specified as a fixed value or a function Real ≥ 0	0
Reserve Proportion	The proportion of off-allocation flow which cannot be allocated	Percent	Mandatory Can be specified as a fixed value or a function Real ≥ 0 & ≤ 100	0
Threshold seasonal event	A check box to activate the event season	Boolean	Optional Tick Box option to allow true/false entry	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 1 ≤ dd ≤ (days in month) mmm = { Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec}	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 1 ≤ dd ≤ (days in month) mmm = { Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec} Year is 'wrapped' if season end > season start	31 Dec
Max Upstream Request activation	A check box to activate the Max upstream request	Boolean	Optional Tick Box option to allow true/false entry	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 Real ≥ 0 & ≤ 100	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

Reference list

Bibliography

Browser not supported