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.

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.

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:

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:

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.

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 right¹, 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:

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)

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.

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.

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:

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.

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.

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:

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:

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.)

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:

These steps are described in detail in the following subsections.

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).

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.)

Once the solver has the Dominant Cutback, it cuts back the dominant account’s appropriation by this amount

and then determines if any subordinates can be cutback better to satisfy the dominant account.

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.

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:

If the candidate is a diverter, the solver:

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.