Accounting : Water Rights Allocation : Computing Appropriation
Computing Appropriation
There are two ways to compute the appropriation, with and without subordination. Depending on method selection, without subordination may also include special calculations for accounts sharing a priority date. Computing appropriations without subordination is described first, followed by the modifications used to model subordination.
Computing Appropriation Without Subordination
To compute the appropriation for a storage right or diversion right, the solver first proposes an appropriation, then determines if this appropriation would short downstream seniors, If so, the appropriation must be cut back, and the solver determines how much it must reduce the appropriation. The cutback results in the maximum appropriation that is legally permitted. The following describes the details of the solver’s logic in this process. The next section describes the logic of the solver when subordination relationships exist between rights in the model.
Note:  When negative flows are allowed: Before proposing an allocation, each passthrough account with the Allow Negative Flow method is visited and the Temp Available Before Appropriation is set to the value of the Temp Available For Appropriation. This is done to record the condition of the system before each right is visited. If the available is already negative, then any allocation to upstream juniors cannot make it more negative, but will not try to undo the negatives.
The solver proposes an allocation to the Diversion or Storage Account by setting its supply from the designated allocatable flow supply chain passthrough account at the appropriation point to be the smaller of the following:
• The Storage or Diversion Account’s Appropriation Request slot value
• The water available in the allocatable flow passthrough account as given by the passthrough account’s temporary slot Temp Available For Appropriation. This temporary slot reflects appropriations from the allocatable flow supply chain to senior rights by the current invocation of the solver. The Available for Appropriation is computed each time the passthrough account solves in the cloned network created by the solver. It reflects the available water in the passthrough account including the sum of inflows, slot inflows, transfers in, transfers out and diversions on that account; it does not include the account’s gain/loss, lag, or return flows.
Note:  The Shortage slot on the Storage or Diversion Account does not bound the appropriation. Thus supplies other than allocatable flow (e.g. releases from upstream storage) that help to satisfy the request do not reduce the allocatable flow appropriations.]
As soon as the solver sets the supply that diverts the proposed allocation from the allocatable flow supply chain, the cloned accounting network solves. The diversion of water from the allocatable flow supply chain could possibly cause negative flows in downstream passthrough accounts where senior rights have already diverted water. These negatives are reflected in the Temp Available For Appropriation slot on downstream passthrough accounts in the allocatable flow supply chain. A negative flow indicates that the proposed appropriation would short a downstream senior storage or diversion right. The magnitude of the shortage is:
• When negative flows are not allowed, the shortage is the absolute value of the negative flow found in the Temp Available For Appropriation slot.
• When the Allow Negative Flows method is selected on the passthrough account, the shortage is computed as follows:
Abs(Temp Available For Appropriation - min(Temp Available Before Appropriation,0))
This modification is made so that if the available before appropriation is already negative, then the shortage is computed as the additional impact by this upstream allocation, not the total negative flow.
For senior downstream instream flow rights, a shortage manifests as a positive value in the Instream Flow Account’s Shortage slot.
The solver inspects the shortage at allocation points for Diversion and Storage Accounts, and checks the Shortage slots of Instream Flow Accounts only for the rights that are senior to the account for which the proposed appropriation was just made. The solver does not check for shortages at points between senior downstream appropriation points, nor does it check for shortages at the bottom of the subbasin, if the bottom lies downstream of the most downstream senior right. (The solver has tables to direct it to the most-downstream senior in an expedient manner.)
If, upon inspection, the solver finds that there is no induced shortage for any downstream senior right, the proposed appropriation stands, and the solver moves on to visit the next-in-priority water right.
Note:  Based on an account’s method selections, there are cases in which accounts record the amounts they could have appropriated, but do not make the appropriation. For these accounts, the resulting appropriation is recorded in the Appropriation Request slot and the proposed appropriation is set to zero before the solver moves to the next-in-priority account.
If, however, the solver finds that there are any downstream senior shortages induced by the proposed appropriation, the solver identifies the most downstream shorted senior. It pushes onto a stack all passthrough accounts in the supply chain between the proposed allocation and the most-downstream senior shortage. The initial value of the cutback to the proposed allocation is the absolute value of the shortage on the most downstream shorted senior. The solver then goes through accounts from downstream to upstream, propagating the shortage upstream and applying gains/losses, to determine how much the proposed appropriation must be cut back to result in no shortages to downstream seniors. (The use of the stack enables the solver to solve upstream back to the appropriation point, and take the proper branch when solving upstream in the face of confluences of any sort.)
The solver visits each passthrough account on the stack in downstream to upstream order, keeping track of the cumulative shortage (CumShort). As it pops a passthrough account from the stack, it applies gains/losses to the CumShort that is propagating upstream. If the passthrough account is an appropriation point for a senior diverter, the gain/loss of the passthrough account is applied to the CumShortage, then the solver checks for a shortage as computed above. If there is a shortage value, the solver compares its absolute value with the current value of CumShortage, and takes the greater value as the CumShort, then continues to the next upstream passthrough account. If the passthrough account is an appropriation point for an Instream Flow Right, additional checks must be made to determine the correct CumShortage value. (See following paragraph.) When the solver reaches the most upstream account on the stack, which has the current proposed appropriation, the CumShort shortage is the amount that the proposed appropriation must be cut back in order to honor the downstream senior rights.
If, as it pops the passthrough accounts off the stack, the solver encounters a passthrough account on a Control Point object that has a senior Instream Flow right1, it checks the Shortage slot on the Instream Flow Account (IFA). If Shortage > 0, then several criteria are examined to determine the correct amount to be added to the CumShortage. The IFA call is the minimum of:
• Shortage; (positive value; amount by which the IFA right is not met);
• the Appropriation Request + Allocatable Flow Deficit where Allocatable Flow Deficit is the absolute value of a negative Outflow of the passthrough account;
• the Available Allocatable Flow + Allocatable Flow Deficit
where the Available Allocatable Flow is a slot whose value was recorded as the outflow of the passthrough account when the IFA was in priority; and
• Delta NF = Available Allocatable Flow - current Outflow value of passthrough account.
Following is a pseudocode version of the solver logic for checking if downstream seniors are shorted as a result of the proposed appropriation: (PTA = passthrough account)
CumShort = 0.0 (maintained as a positive value, hence the use of the ABS operator)
For each passthrough account on the Stack in d.s. to u.s. order:
If (PTA does not have a senior appropriation OR
PTA has a senior Div appropriation AND TempAvailableForAppropriation >= 0)
CumShort = (CumShort)/(1-GainLossCoeff)

Else if PTA has a senior Div appropriation AND shortage < 0)
CumShort = Max{(CumShort)/(1-GainLossCoeff), ABS(shortage)}
Else if PTA is on an object with a senior Instream Flow Acct (IFA) appropriation
If Shortage > 0
Call = Min (Shortage,
Appropriation Request + NatFlowDeficit
Available Allocatable Flow + NatFlowDeficit,
DeltaNaturalFlow )
CumShort = Max{CumShort, Call)
Endif
The CumShort is reset to the call if the call is larger than the current CumShort. When the stack is empty (the solver has reached the most upstream account on the stack), the CumShort is the amount that the proposed appropriation must be cut back. The algorithm then reduces the proposed appropriation by this amount, which causes the cloned accounting system to solve and moves on to the next prioritized account.
Computing Appropriation Without Subordination for Equal Priority Accounts
If two or more accounts have the same priority date, a method must be selected under the Account Equal Priority Allocation category on the computational subbasin to specify how to handle appropriations in this case. The following section describes these computations under the Share Proportionally with Limits method.
Note:  This method cannot be used in conjunction with subordination and that instream flow accounts cannot be shared priority accounts.
The overall approach for this method is to iteratively share available water based on a calculated proportion equal to available flow divided by cumulative water right, with the proportion for an account limited by any downstream smaller proportion calculated for another account. The steps for this method are as follows:
1. Individually for each account in the group:
– A proposed appropriation is calculated for the account in a normal fashion as discussed above, except the proposed appropriation is not limited by the Storage or Diversion Account’s Appropriation Request slot value. The proposed appropriation will thus represent all of the available water at this account’s diversion point minus any needed for downstream seniors.
– The proposed appropriation is set into the account’s Temp Available For Shared Priority slot (temporary2).
– The proposed appropriation is set to zero and the cloned accounting system will resolve reflecting no water diverted for the account.
– Process is repeated for the next account in the group, resulting in a computation for each account that is independent of the other accounts in the group.
2. For each account in the group:
– Compute a cumulative right that is a total of the appropriation requests for this account and any in the group that are upstream.
– Calculate a bypass value for downstream seniors that is the Temp Available For Appropriation slot value from this account’s associated passthrough account minus this account’s Temp Available For Shared Priority slot value.
3. Loop through the following until additional proposed diversions for all accounts in the priority group are zero.
– For each account in downstream to upstream order:
1. Get an adjusted available water value by taking the Temp Available For Appropriation slot value from this account’s associated passthrough account and subtracting out the bypass value and any additional diversions made for downstream accounts in this iteration of downstream to upstream accounts.
2. Set an available water variable to be the minimum of adjusted available water or the account’s Temp Available For Shared Priority value.
3. Compute a proportion as the available water variable divided by the account’s cumulative right.
4. Limit the proportion to a maximum of 1.0, and limit it so that it is not greater than any proportion previously calculated for a downstream account in this iteration of downstream to upstream accounts.
5. Compute an additional diversion value as the proportion times the account’s Appropriation Request slot value.
6. Limit the additional diversion if it plus the proposed appropriation already set for the account will be greater that the account’s Appropriation Request value.
7. Record the additional diversion value for this account for use in adjusting available water for further upstream accounts as described above.
– Set the calculated additional diversions for all accounts in the priority group onto their proposed appropriation values, which will resolve the cloned accounting system and result in new available water values for the next trip through the loop.
Note:  The loop is exited when calculated additional diversions for all accounts in the priority group are zero.
4. Check that downstream senior accounts were not shorted by the appropriations calculated for the equal priority accounts. This can happen in certain circumstances when equal priority accounts are on different branches that feed into a downstream senior. For each equal priority account:
– Find if a downstream senior was shorted and if so, find all the equal priority accounts whose appropriation points are upstream of this senior’s appropriation point and sum the appropriations for these accounts.
– Calculate a reduction proportion as the shortage amount at the senior divided by the sum of the appropriations for the upstream equal priority accounts.
– Reduce the appropriations for the upstream equal priority accounts by the calculated proportion. This causes the system to resolve.
– Recheck to see if any downstream seniors of the current account are shorted. If so, repeat the above steps. If not, move on to the next equal priority account and repeat the process until all the equal priority accounts have had the downstream seniors check.
When appropriations are solved for all account’s in this priority group, move on to the next priority and process as in the previous section if it is a single account or as described in this section if it is a group of accounts sharing the priority.
Computing Appropriation with Subordination
Sometimes holders of water rights make agreements that are exceptions to the strict priority-based allocation. RiverWare allows some agreements to be modeled with a subordination relationship between a senior right-holder and a junior right-holder. In such a relationship, the senior gives up allocated water to reduce a junior’s shortage.
When a right is involved in a subordination relationship with another right, the algorithm for computing its appropriation is more complex than that described in the previous section. To describe the effect of subordination on the appropriation, let us define some terms (these terms are defined here strictly for the purpose of facilitation this discussion; they are not widely-used):
A right S may be modeled as subordinate to a junior right J by selecting a method on the account representing J, and putting S in a list of J’s subordinates. We call S the subordinate, and we call J the dominant right. J may have more than one subordinate right.
The subordination relationship is defined through method selection on each dominant account. A list is specified of the subordinate accounts on the Subordinate Rights slot. See Subordination of Right for details on the storage account. See Subordination of Right for details on the diversion account.
Appropriations for the subordinates are computed in priority order in the normal fashion (as if they were not involved in a subordination relationship), but when the appropriations for their dominant rights are computed (later, since a dominant right is necessarily junior), the subordinates’ appropriations may be reduced to accommodate the dominant rights. Subordinate appropriations are reduced only if such reduction will enable the dominant right to take more, (but not more than its appropriation request). That is, the subordinate to be cut back must be upstream of the shorted right, and it must have some allocated water to give up.
To compute the best appropriation for a dominant right, the solver first proposes an appropriation, then determines if this appropriation would short downstream seniors. If so, either the dominant appropriation must be cut back or one or more subordinate appropriations must be cut back (or both). The dominant appropriation must be cut back to accommodate downstream seniors that are not subordinate, but only if no subordinate can be cut back to satisfy the non-subordinate seniors. If the most-upstream subordinate is downstream of a shorted non-subordinate senior, the dominant appropriation must be cut back. On the other hand, if a subordinate lies upstream of a shorted non-subordinate downstream senior, adjustments to the subordinate appropriation might eliminate the apparent shortage at the non-subordinate. Clearly, the downstream seniors must be considered in upstream-to-downstream order to avoid making cutbacks that have no beneficial effect.
Further complicating matters, when a dominant right has two or more subordinates, the relative priorities of the subordinates are taken into account, so that the most-junior subordinate gives up water first (if it otherwise makes sense to do so). To address this complication, the algorithm processes downstream seniors in upstream-to-downstream order, collecting candidates for cutbacks; these are the subordinates that have already been encountered in our upstream-to-downstream processing of downstream seniors, and that have been allocated something to give up.
Details of the Solution Logic
Following are details of the solver’s logic.
The solver proposes an allocation to the dominant Diversion or Storage Account by setting its supply from the designated allocatable flow supply chain passthrough account at the appropriation point to be the smaller of the following:
• The Storage or Diversion Account’s Appropriation Request slot value
• The water available in the allocatable flow passthrough account as given by the passthrough account’s temporary slot Temp Available For Appropriation. This temporary slot reflects appropriations from the allocatable flow supply chain to senior rights by the current invocation of the solver. The Available for Appropriation is computed each time the passthrough account solves in the cloned network created by the solver. It reflects the available water in the passthrough account including the sum of inflows, slot inflows, transfers in, transfers out and diversions on that account; it does not include the account’s gain/loss, lag, or return flows.
Note:  The Shortage slot on the Storage or Diversion Account does not bound the appropriation. Thus supplies other than allocatable flow (e.g. releases from upstream storage) that help to satisfy the request do not reduce the allocatable flow appropriations.
Note:  So far, this is the same as in the non-subordination case.
Determining Resulting Downstream Shortages
As soon as the solver sets the supply that diverts the proposed allocation from the allocatable flow supply chain, the cloned accounting network solves. The diversion of water from the allocatable flow supply chain could possibly cause negative flows in downstream passthrough accounts where senior rights have already diverted water.
These negatives are reflected in the Temp Available For Appropriation slot on downstream passthrough accounts in the allocatable flow supply chain. A negative flow indicates that the proposed appropriation would short a downstream senior storage or diversion right. The magnitude of the shortage is:
• When negative flows are not allowed, the shortage is the absolute value of the negative flow found in the Temp Available For Appropriation slot.
• When the Allow Negative Flows method is selected on the passthrough account, the shortage is computed as follows:
Abs(Temp Available For Appropriation - min(Temp Available Before Appropriation,0))
For senior downstream instream flow rights, a shortage manifests as a positive value in the Instream Flow Account’s Shortage slot.
The solver determines the shortage at appropriation points for Diversion and Storage Accounts, and checks the Shortage slots of Instream Flow Accounts only for the rights that are senior to the account for which the proposed appropriation was just made. The solver does not check for shortages at points between senior downstream appropriation points, nor does it check for shortages at the bottom of the subbasin, if the bottom lies downstream of the most downstream senior right. (The solver has tables to direct it to the most-downstream senior in an expedient manner.)
Note:  So far, this is the same as in the non-subordination case.
Note:  Based on an account’s method selections, there are cases in which accounts record the amounts they could have appropriated, but do not make the appropriation. RiverWare does not support this method selection on a dominant account.
To determine which, if any, appropriations need to be cut back, the solver visits each downstream senior right, in upstream-to-downstream order. If two or more downstream seniors appropriate from the same location (passthrough account in the Allocatable Flow supply chain), these rights are visited in junior-to-senior order.
For each downstream senior visited, the solver proceeds as follows:
1. Determine if the senior is a candidate for exchange.
2. Compute any necessary cutback to the dominant based on a shortage at the downstream senior.
3. Apply the cutback.
4. Exchange allocated water between candidates and dominant, considering only those candidates junior to the shorted senior, if the senior is a subordinate, and considering all candidates if the shorted senior is not a subordinate.
These steps are described in detail in the following subsections.
Determine if Senior is a Candidate for Exchange
If the downstream senior being visited is not one of the subordinates of the dominant, the solver proceeds as described in the following subsections.
If the downstream senior right being visited is a subordinate and is a diverter that has a non-zero appropriation, the solver puts this subordinate into a list of candidates for cutbacks, then proceeds as described in the following subsections. (If this subordinate has no appropriation, it cannot be shorted by the dominant appropriation, and it cannot exchange water with the dominant right.)
If the downstream senior right being visited is a subordinate and is an instream flow account, it is put in the list of candidates if and only if it is shorted and there are other candidates in the list. (If it is shorted, it will cause a cutback to the dominant and then, by being a candidate, it can give back all the cutback amount). If the account is put into the list of candidates, the solver proceeds as described below, but if the account is not put into the list, the solver proceeds to the next downstream senior (the Instream Flow right will suffer a shortage).
Compute Dominant Cutback
The solver now determines if the downstream senior right being visited is shorted, and if so, what is the amount the dominant right’s diversion must be cut back. If the downstream senior right is not shorted, the Dominant Cutback amount is zero, and the solver proceeds to visit the next downstream senior right. If the downstream senior right is shorted, the solver proceeds as follows.
The solver pushes onto a stack all passthrough accounts in the supply chain between the proposed allocation and the senior shortage. The initial value of the cutback to the proposed allocation is the shortage (as described in Determining Resulting Downstream Shortages, above) on the downstream shorted senior. The solver then goes through accounts from downstream to upstream, propagating the shortage upstream and applying gains/losses, to determine how much the proposed appropriation must be cut back to result in no shortages to the (non-subordinated) downstream senior. (The use of the stack enables the solver to solve upstream back to the appropriation point, and take the proper branch when solving upstream in the face of confluences of any sort.)
The solver visits each passthrough account on the stack in downstream to upstream order, keeping track of the cumulative shortage (CumShort). As it pops a passthrough account from the stack, it applies gains/losses to the CumShort that is propagating upstream.
When the solver reaches the most upstream account on the stack, which has the current proposed appropriation (the dominant account), the CumShort shortage is the Dominant Cutback, the amount that the proposed appropriation could be cut back in order to honor the downstream senior right. (Because we are visiting downstream seniors in upstream-to-downstream order, and making all necessary corrections, we know that there are no shortages induced at seniors above the one we are visiting, so we only need to apply gain/loss to the shortage at this downstream senior (being visited in upstream-to-downstream order) to determine the Dominant Cutback amount.)
Cut Back Appropriation to Dominant Right
Once the solver has the Dominant Cutback, it cuts back the dominant account’s appropriation by this amount
dominant appropriation = dominant appropriation - Dominant Cutback
and then determines if any subordinates can be cutback better to satisfy the dominant account.
Exchange Appropriated Water with Candidate Subordinates
If the solver’s candidates list is empty, there is nothing more to do with this downstream senior, and the solver proceeds to the next downstream senior account.
Note:  All of the candidates are upstream of the shorted downstream senior (except the shorted downstream senior itself) and may be senior or junior to the shorted downstream senior.]
If the candidates list is non-empty, the candidates are inspected one at a time, in junior-to-senior order.They are cut back as much as they can be cut back to satisfy the dominant account. To do this, the solver:
1. Determines if the candidate is an instream flow account. If so, it gives back all the remaining Dominant Cutback to the dominant account:
dominant appropriation = dominant appropriation + Dominant Cutback
Dominant Cutback = 0
2. Removes the candidate from the candidates list. Then it stops considering candidates and moves to the next downstream senior.
If the candidate is a diverter, the solver:
1. Finds the aggregate loss aggLoss between the dominant and the candidate,
2. Computes an amount to cut back the candidate, which is the lesser of what the candidate appropriates and what the dominant was cut back, adjusted for gain/loss:
candidateCutback = aggLoss *
min(candidate appropriation / aggLoss, Dominant Cutback)
3. Cuts back the candidate:
candidate appropriation = candidate appropriation - candidateCutback
4. Reduces the dominant’s cutback by this amount adjusted for gain/loss:
Dominant Cutback = Dominant Cutback - candidateCutback / aggLoss
5. Gives the water back to the dominant account:
dominant appropriation = dominant appropriation + candidateCutback / aggLoss
6. If the candidate’s appropriation is now zero, remove the candidate from the candidates list.
This process is repeated for every candidate until the Dominant Cutback is zero or there are no more candidates in the list.
Return {Slot Name,Value} or {Slot Name, DateTime, Value} List to Rule
After the solver has visited each water right in the subbasin in priority and computed their allocations and set the allocations on the cloned system, the solver creates a list of {slot name, value} pairs in the case of SolveWaterRights(), or {slot name, date-time, value} triplets in the case of SolveWaterRightsWithLags(), of allocations that are returned by rule function. The rule can access these pairs or triplets and set the slot equal to the value at the appropriate time.

Instream Flow Accounts reside on Control Points, which do not support any sort of diversion, so an appropriation point cannot serve both an instream flow right and a diversion or storage right.

This temporary slot is not stored in the model file, and is present for debugging purposes only, and may be removed from RiverWare at any time; do not write rules that use it.

Revised: 08/02/2021