skip to main content
Water Rights Allocation
Accounting
Water Rights Allocation
This document describes the use of a new rule function in RiverWare that allocates water in the accounting network to water rights (accounts) according to priorities given by the priority date on the accounts. Earlier dates have higher priority than later dates i.e., those with an earlier priority dates have first right to the use the available water over those with later priority dates. This function, along with the methods on accounts and objects, and new linking configurations, support modeling water allocation under the doctrine of Prior Appropriation.
Previously, users have implemented a water rights allocation algorithm using logic created in rules. Although this problem can be solved with rules, the solution is sufficiently complex that the resulting ruleset is large, difficult to maintain, and the resulting model runs are inherently slow for a moderately sized basin. To address these modeling issues, CADSWES has developed a rule function that calls a solver and returns the correct allocations.
First, we present the assumptions/requirements considered in the design and a general description of the solver. Next we describe how to set up a model and rules to use the solver. Finally, the detailed solution algorithm and additional modeling recommendations are presented.
Topics
Requirements
The solver’s purpose is to determine prioritized water allocations according to the doctrine of Prior Appropriation. In particular, the solver meets the following requirements:
• Three distinct types of water rights can be represented in RiverWare by legal accounts, and can receive priority allocations:
– The right to divert from a stream, represented in RiverWare by a Diversion Account.
– The right to store water in a reservoir, represented in RiverWare by a Storage Account.
– The right to minimum in-stream flow, represented in RiverWare by an Instream Flow Account.
• Water rights (legal accounts) that receive priority allocation have a unique priority date, i.e., no two water rights may have the same priority date.
• A right’s allowed quantity of water may be described in various ways on legal documents or in practice; the model capabilities must be flexible enough to represent these, and to be extensible to add representations later that are not initially provided.
• Allocation to a junior right may not short the available water to a senior right.
• Some rights are subject to physical constraints such as the physical capacity of a diversion structure or the size of a reservoir pool.
• Some rights are subject to legal constraints such as accrual-based maximums. Some legal constraints are defined in terms of the state of the network after senior rights have been satisfied, such as minimum bypass requirements that are expressed as a function of the flow in the river.
• The effects of an upstream allocation on a downstream senior right must take into account lags and losses as water moves downstream.
• The solver is intended to allocate only Allocatable Flow. Hence, it does not solve for any diversions from storage accounts, or releases from storage accounts to meet downstream needs. Such allocations are expected to be addressed with other rules and are not priority-date driven.
• The solver can be executed more than once during a timestep, with different sets of instream flows being allowed to call water from junior upstream rights.
Modeling Approach
To meet these requirements, RiverWare developers designed a rule function that calls a network water rights allocation solver, a new type of legal account to model instream flow rights, some new linking configurations for accounts, and methods on accounts to support the network allocation solver. The following is a summary of the modeling approach.
The water rights solver is designed to work in a rulebased simulation model with accounting. The model must have an underlying accounting network as described in the following sections and the rule set must make calls to the predefined SolveWaterRights() function or, if the accounts have lag times, SolveWaterRightsWithLags(). In particular, the model should consist of the following.
• Simulation objects with the appropriate methods selected to describe the physical network.
• Legal accounts, i.e., Storage Accounts, Diversion Accounts and Instream Flow Accounts, with priority dates on the simulation objects to represent the prioritized water rights.
• An allocatable flow supply chain, modeled by creation of passthrough accounts on the river/reservoir objects (including Reaches, Confluences, Gages, etc.), and the linking together of these passthrough accounts.
• Supplies that link the rights-holding accounts to the allocatable flow supply chain’s passthrough accounts to represent the appropriation points from allocatable flow.
• A computational subbasin that contains the objects involved in the allocation, including all objects with accounts in the allocatable flow supply chain and objects with rights-holding accounts. The computational subbasin must have the appropriate methods selected to allow execution of the water rights solver.
• A result that includes a rule that calls the predefined function SolveWaterRights() or SolveWaterRightsWithLags().
Each of these components is described in greater detail in the following sections.
Simulation Objects and Accounts
Allocations can be computed by the solver for the following configurations:
• A diversion right modeled by a Diversion Account on a Water User or AggDiversionSite Object.
• A storage right on a reservoir modeled by a Storage Account on a Reservoir Object. The reservoir may be in-stream, in which case it contains a passthrough account representing the flow of non-stored native water through the reservoir. It may be off-stream, in which case it receives water from a Reach Object through a Diversion Object.
• An instream flow right modeled by an Instream Flow Account on a Control Point Object; the Control Point sits between Reaches, Confluences, Stream Gages and other object representing the stream.
These water rights are described in various ways in legal documents, so each account with water rights expresses its entitlements through method selections allowing for a variety of ways to express the right’s requested water.
In general, each right makes an initial request based on the legal description of the right. Next, the state of the system at the time of allocation might restrict the initial request by either physical constraints or legal constraints to produce a net Allocation Request. The difference between the Initial Request and the amount allocated is the shortage, which represents the portion of the demand that is not met by the allocations from native water. Depending on the method selections on the account, the account may have slots Initial Request and Shortage, which rule sets can use to compute reservoir releases or transfers from other sources or water to meet remaining demand. See “Creating a Model” for details on how to represent each kind of right.
Allocatable Flow Supply Chain
Based on the doctrine of Prior Appropriation, only allocatable flow is allocated to the water rights holder. Water already stored in reservoirs or released from those reservoirs is not considered allocatable flow. In this document, water that has been stored and is managed as releases from storage is called “Project” water. To track the allocatable flow through the simulation objects, the model should be configured to have one chain of accounts and supplies (links between the accounts) that is continuous through the portion of the simulation model for which water rights solver needs to be applied. These passthrough accounts are exclusively labeled by a water type that identifies them as the allocatable flow supply chain, from which appropriations are to be made.
An example of a allocatable flow supply chain is shown in blue in Figure 6.1. Each object has a passthrough account called “Allocatable Flow” which is linked via supplies to other passthrough accounts of the same name.
Linking Rights-Holding Accounts to Allocatable Flow
Allocations can be computed by the water rights solver for the following linking configurations between the allocatable flow supply chain and the water rights accounts:
• A Diversion Account on a Water User or AggDiversionSite Object is linked to the allocatable flow supply chain passthrough account on a Reach via a link is of type Diversion/Return Flow.
• A Storage Account on a Reservoir Object. Two configurations are recognized:
– For an in-stream reservoir a Storage Account with the storage right is supplied by the passthrough account of the allocatable flow supply chain on the same reservoir via a supply of type Transfer.
– For an off-stream reservoir, the Storage Account is supplied by a passthrough account on a Diversion Object via a supply of type Inflow/Outflow, which is in turn supplied by a passthrough account on the linked Reach via supply type Diversion/Return Flow.
• An Instream Flow Account on a Control Point Object does not need to be explicitly linked to the allocatable flow passthrough account because the Flow slot on the Instream Flow Account adds up the Inflow slots of all the passthrough accounts on the Objects.
Figure 6.1 is an example of each of these water rights linked to a allocatable flow supply chain.
Figure 6.1  Allocatable Flow supply chain (blue) and project water (red and green)
A Computational Subbasin that Contains the Objects
The water rights allocation solver refers to a computational subbasin that specifies the objects that contain accounts involved in the solution. The computational subbasin also has slots and methods that are used to control the rule function that uses the subbasin. The method categories pertinent to water rights accounting allow a water rights allocation solver to be used with the subbasin and allow the subbasin to disaggregate annual demands into per-timestep demands. The subbasin is described in more detail in online help document Objects, Section on Computational Subbasin.
At the beginning of the run, if the subbasin is enabled, the subbasin performs checks for each selected method in all categories. For the Prior Appropriation method in the Water Rights Allocation category, the subbasin creates a set of tables describing the topology of the subbasin. It locates all water accounts with priority dates, sorts them, and assigns a value to the account’s Temp Priority slot: 0 for the most senior account, and increasing according to later priority dates.
The subbasin records, for each prioritized account, all its supply chains. For each of its supply chains (a chain whose head is the appropriation point for the prioritized account), the subbasin assigns a chain identifier. The tables also record all downstream seniors, reachable from each supply chain. The solver also creates bitmaps to determine if a given account is in a given supply chain. These tables are used during the run by the solver. If a run is paused and resumed, it is easy to see that any topological changes in the model during the pause will render these tables obsolete and can cause the solver to fail in unpredictable ways. In other words, do not make any such changes during a run!
The subbasin also checks for some common modeling errors and reports errors that it finds.
The Rule Set
The ruleset must consist of the following.
The SolveWaterRights() and SolveWaterRightsWithLags() Rules Functions
The water rights allocation solver is executed by calling the predefined function SolveWaterRights() or SolveWaterRightsWithLags() from a rule. This function is called with the following arguments:
• The name of the computational subbasin that identifies the set of objects (and contained accounts) on which appropriations will be made by this solver
• A water type identifying the allocatable flow supply chain from which allocations will be made by this solver
• A date that controls the behavior of the instream flow rights during the solution computation
The SolveWaterRights() predefined rule function returns a list of {slot name, value} pairs, which the rule uses to place the value in the appropriate slot. The function executes the methods on the specified computational subbasin which perform the allocation and return values to the rule. As with other predefined functions, no values in the model are set or modified during the function call. Values are only set at the uppermost level of the rule. See “SolveWaterRights and SolveWaterRightsWithLags” in RiverWare Policy Language (RPL) for details about this function.
The SolveWaterRightsWithLags() predefined rule function works much like SolveWaterRights(), but is used when the subbasin passthrough accounts contain lags. It returns a list of {slot name, date-time, value} triplets, which the rule uses to place the value in the appropriate slot at the appropriate timestep. The timestep given will reflect the Local Timestep Offset of the account on which the slot resides. It is some number of timesteps after the current rules-controller timestep, and reflects the relationships of the account to other accounts in the subbasin based on their respective cumulative lag times to the end of the subbasin.
Overall Rules Order
This section provides an overview of the approach used to allocate water and simulate the network. The model proceeds as follows assuming instream flows are modeled:
1. Initialize the accounting system so that the legal entitlements are known or can be determined at run time. This means that all water rights accounts must have an initial request from which their demands can be computed, or, in the case of storage rights, their underlying reservoirs have methods selected to define the bounds of a Conservation Pool, or, in the case of instream flow rights, their underlying control points have a method selected to define a reference level from which their initial requests can be computed.
2. Provide the local inflows to the accounting system so that the allocatable flow is known. This is done by rules or Object Level Accounting methods that transfer values from Hydrologic Inflow or Local Inflow slots on the Simulation Object to the Slot Inflow slot on the Allocatable Flow passthrough accounts. If Object Level Accounting Methods are used, they should be configured to execute (see “Reconciling the Accounting and Physical Systems” for details) at Beg of Run, Beg of Timestep, or Beg of Timestep Once. Typically, the Copy Slot to Slot Inflows method can be used; see “Copy Slot to Slot Inflows” for details.
3. Invoke the solver on the allocatable flow supply chain by calling the predefined function SolveWaterRights() or SolveWaterRightsWithLags() with a very early controlling date, i.e., earlier than the earliest Instream Flow right. (if modeling instream flows) to allocate allocatable flow without regard to instream flow rights (they cannot make calls). The quantity of allocatable flow that is available to each Instream Flow account is saved in the slot Available Allocatable Flow so it can be used by one or more later invocations of the solver that allow these rights to make calls.
4. Execute other rules to operate reservoir Storage Accounts to meet downstream unmet demands that could not be met by allocatable flow.
5. For each Instream Flow water right, from most senior to most junior, do the following:
a. Call SolveWaterRights() or SolveWaterRightsWithLags() predefined function to re-solve, with a controlling date at or later than the current Instream Flow right, but before the next one. The solver will attempt to satisfy demands of each Instream Flow Account whose priority date is older than or equal to the controlling date. These Instream Flow demands are satisfied by both the allocatable flow available at the priority date, and also flow that passes through the object as a result of reservoir storage releases. In this invocation, allocation to upstream juniors are not allowed to short the Instream Flows that are senior to or at the priority implied by the controlling date.
b. Again execute rules to operate reservoir Storage Accounts to meet other objectives.
c. Reconcile the accounting solution (reservoir accounting releases, appropriations, and other accounting diversions) with the physical simulation objects (reservoir releases, diversions from reaches) and simulate the physical system
In this approach, water rights and the accounting solution drive the simulation system. This is different from the typical accounting model in which the accounting system solves after the physical system.
Creating a Model
This section describes the steps necessary to create a model that uses the water rights solver. Each type of right is described along with the methods available on both the containing object and the account. Next, the computational subbasin and its methods are described. Finally, the allocatable flow supply chain from which the solver allocates and other assumptions made about the model are discussed. In general, only an overview of the methods is presented in this document; details are provided in the reference material. Links are provided to take you to the appropriate sections of the reference material.
Storage Rights
Storage rights are modeled with Storage Accounts on any of the four reservoir objects: Storage Reservoirs, Level Power Reservoirs, Sloped Power Reservoir, and Pumped Storage Reservoirs.
Object Methods
If the capacity of the Storage Account is limited to the volume of the conservation pool, select either Conservation Pool or Conservation and Flood Pools in the Operating Levels category on the reservoir. If the None method remains selected, this physical constraint will not be enforced and the Fill Conservation Pool and Fill Conservation Pool with Diversions methods on the Storage Account will not be available to calculate initial requests. The specified operating levels are not required to match entries in the reservoir’s Elevation Volume Table, however, the Elevation Volume Table must cover the range of values in the Operating Level Table. See “Cubic Bank Storage” in Objects and Methods for details on these methods.
Account Methods
On each Storage Accounts that has a water right, it is necessary to specify the following:
• In the Water Right category, the Priority Right must be selected. This is the same as selecting the Has Priority Date toggle on the General tab of the Open Account (configuration) dialog. Specify a unique priority date.
• In the Initial Request category, select the Specify Initial Request, the Fill Conservation Pool, or the Fill Conservation Pool with Diversions method to specify how the initial water right is determined. In the Specify Initial Request method, the user can specify (via input, dmi, or rules) the Initial Request slot. If the Fill Conservation Pool method is selected, initial allocations to Storage Accounts are limited to that amount which will fill up the conservation pool on the reservoir. If the Fill Conservation Pool with Diversions method is selected, initial allocations to Storage Accounts are limited to that amount which will fill up the conservation pool on the reservoir and meet diversions totaling the sum of the Initial Requests of all direct diverters from the storage account. The total volume in all Storage Accounts on a reservoir contributes to the conservation pool volume, regardless of the ownership of the water in these accounts. For this reason, in order to prevent a single storage account from holding all the water in the conservation pool, the Conservation Pool Fill Factor category may be used. This category contains methods that allow a fraction of the conservation pool (and diversions) to be allocated, thereby reserving some for other accounts. See “Initial Request” for additional information.
• If lagged return flows entering the Storage Account are to be credited to the appropriation from allocatable flow, select the method Return Flow Credit in the Appropriation Request Adjustment category.
Storage rights might be subject to legal constraints as well as to physical constraints. Examples of legal constraints are minimum bypass constraints and accrual-based maximums. If there is a minimum bypass, select a method in the Min Bypass category. Currently available is the Fraction of Flow Above Min method. See “Min Bypass” for additional information on this method.
When the Fill Conservation Pool with Diversions method or the Fill Conservation Pool method is selected, the solver saves a copy of the resulting Appropriation Request slot value in the Initial Request slot, if the solver finds that the Initial Request slot value is not already defined. This use of the Initial Request slot differs from the standard usage in that its value reflects the application of legal and physical constraints, and in that it is not computed on every call to the solver.
Linking Accounts
Allocations to Storage Accounts on in-stream reservoirs from the allocatable flow supply chain on the same reservoir are made through transfer type of links (supplies), as shown in Figure 6.2.
Figure 6.2  Allocatable Flow supply chain transferred to storage on the same reservoir
Off-stream reservoirs with storage rights receive allocations diverted from the main river or an in-line reservoir. They must be linked to the Reach or Reservoir Object through a Diversion Object. The allocation is subject to the physical capacity of the diversion structure at the point of diversion (Diversion Capacity slot on the Reach). Below is a view of this setup. Water is allocated from the Allocatable Flow supply chain to the 1920 Storage right, but it must go through a passthrough account on the DIVOBJ Diversion Object. The passthrough on the Diversion Object is linked to the Allocatable Flow passthrough account on the Reach via a Diversion type of supply (link). The Inflow of the Storage Account on the offstream reservoir gets a supply from the Outflow of the passthrough account on the Diversion Object.
Figure 6.3  Allocatable Flow supply chain diverted to a diversion object, then to the off-stream reservoir
You can have multiple water rights on the offstream reservoir. There should be one passthrough account on the diversion object for each water right on the reservoir. The water type of the passthrough account on the diversion object does not matter. It can be the same or different than the allocatable flow chain.
Caution:  Storage accounts should not be linked into the allocatable flow supply chain by Inflow/Outflow supplies. In allocating to a Storage Account, the solver will not include the volume of diversions or releases from the Storage Accounts at the current timestep. Such policy decisions are expected to be addressed with rules.
Diversion Rights
Diversion rights are modeled by a Diversion Account on a Water User or AggDiversion Site Object.
WaterUser and Aggregate Diversion Site Object Methods
No additional method selections on the object are required to use the solver.
Diversion Account Methods
In the Water Right category, the Priority Right must be selected. This is the same as selecting the Has Priority Date toggle on the General tab of the account configuration dialog. Specify a unique priority date. In the Initial Request category, select one of the Specify Initial Request, Disaggregate by Subbasin, or Max Permitted methods to specify how the initial water right request is determined. See “Initial Request” for additional information.
For water rights allocation, diversion accounts may only use the Simple Lag method in the Return Flow Route or Split. The Split and Route method cannot be used. See “Simple Lag”, “Return Flow Route or Split”, and “Split and Route” for details.
Diversion rights might be subject to legal constraints as well as to physical constraints. Legal constraints include the following:
• Max Legal Request. This method allows the user to enter a value for the Initial Request that is larger than the legal right. This is useful if you are computing the Initial Request from aggregated or historical data. See “Max Legal Request” for details.
• Min Bypass. If there is a minimum bypass, select a method in the Min Bypass category. Currently available is the method Fraction of Flow Above Min. See “Min Bypass” for details on this method.
Linking
Allocations to a Diversion Accounts is limited by the value in the reach Diversion Capacity scalar slot. If no value is given, no physical constraint is applied. As shown, the Diversion Account’s Diversion slot gets a supply from the Diversion slot on the passthrough account on the Reach.
Figure 6.4  Allocatable Flow supply chain (blue) linked by supplies to a water user diversion account with a diversion right
Instream Flow Rights
An instream flow right is modeled by an Instream Flow account on a Control Point Object. Shown is a a 1910 FISH Instream Flow Account. No supplies are necessary to link this account to other accounts on the Control Point; the Flow slot of the Instream Flow account contains the sum of the Inflows to all the passthrough accounts on the object.
Note:  In Figure 6.5, there are no links; that is, supplies to the instream flow account.
Figure 6.5  Allocatable Flow supply chain (blue), project water (red), and instream flow account (yellow)
Control Point Object Methods
One method category on the Control Point Object contributes to the computation of Initial Request based on storage in upstream reservoirs. This method is on the object rather than the account because it uses information from other simulation objects. The category is Instream Flow Reference Level, from which the user can select the Reservoir Storages Lookup method. This method allows the user to establish a reference level on which the Instream Flow Account can base its water allocation requests. This method executes one timestep each year identified by the Start of Reference Year slot. At that timestep, this method sums the storages at the previous timestep from each of the Reference Reservoirs. The sum is then looked up in the Reference Level Storage Table to determine the Reference Level. The Reference Level is used by the Instream Flow accounts on the object to determine the account’s initial request. See “Reservoir Storages Lookup” in Objects and Methods (Objects/ Control Point/ User Methods/ Instream Flow Reference Level) for details.
Instream Flow Account Methods
In the Water Right category, the Priority Right must be selected. This is the same as selecting the Has Priority Date toggle on the General tab of the account configuration dialog. Specify a unique priority date
In the Initial Request category, select either the Specify Initial Request or the Based on Reference Level method to specify how the initial water right is determined. See “Initial Request” for additional information.
The behavior of the Instream Flow Accounts during the water rights solution depends on the controlling date argument for the SolveWaterRights() or SolveWaterRightsWithLags() function call. The controlling date is one that determines which Instream Flow Accounts can make calls and which only compute their Available Allocatable Flow slot values. The accounts whose priority dates are equal to or earlier (i.e., are senior to) the controlling date are allowed to place calls on junior upstream rights. The call is limited by the value in the already-computed Available Allocatable Flow slot of the Instream Flow Account. Thus, the first call to the solver must have had a controlling date senior to all Instream Flow Account priority dates.
Computational Subbasin
A computational subbasin is defined by the user to specify the objects which are to be part of the water rights solution. On the computational subbasin, select the Prior Appropriation method on the Water Rights Allocation category. (There is only one solver, however, the category allows for future implementation of other allocation schemes.) See “Water Rights Allocation” in Objects and Methods for a description of the slots associated with this method. Once this method is selected, a new category, Account Initial Request, becomes visible. This category allows the user to specify a method to disaggregate annual requests. The available methods are No Method, Periodic Coefficients or Series Coefficients; the user should select the method based on the timestep of the model and the preferred way to input the coefficients. See “Account Initial Request” in Objects and Methods for additional information on these methods.
Data Requirements for the Allocatable Flow Supply Chain
The following model assumptions must be met for the solver to work correctly:
• There is no way for water to leave the allocatable flow supply chain from which this the water rights solver allocates other than through:
– The allocations made by the solver
– Gain Loss slot values which are output. This is accomplished by selecting the appropriate Gain Loss Coefficient method (see “Gain Loss Coefficient”) on passthrough accounts in the chain and then specifying the coefficient (either scalar, series or periodic) if desired. If Gain Loss slot values are not determined by a gain loss coefficient (i.e. they are user input), the solver cannot solve upstream for cutbacks to upstream appropriations.
– In addition, inflows, outflows, non-appropriation transfers, and return flows are assumed to be non-negative throughout the supply chain and there are no existing diversions or (appropriation) transfers to accounts that will not be re-allocated by this method. Slot inflow values may be negative only to the extent that they do not produce negative outflows anywhere in the supply chain at any time during the solution. See the note below for the only exception to this.
• At Instream Flow Accounts, no sibling accounts have negative inflows. If they do, this method cannot solve upstream for cutbacks to upstream appropriations. See the note below for the only exception to this.
Note:  Negative flows at the time of allocation are allowed only if the Allow Negative Flows method is selected on passthrough accounts for the allocatable flow chain on reaches, reservoirs and control points.
• Because the solver relies on the account-solving infrastructure, certain required input values must be known on the accounts so that the supply chain can solve before this method is called. The required knows for account solution are documented in the Accounting reference documentation. See “About Accounts” for details. Following is a summary of the slot requirements for this solver to work.
– On Passthrough and Instream Flow Accounts: Inflow slot values will be propagated from above, except for those at the heads of the tributaries of the allocatable flow supply chain, which do not require Inflow slot values.
– Passthrough accounts not on a reservoir: Slot Inflow must be defined. Gain Loss slot values may not be user input (they may be Output). But a gain loss coefficient (either scalar, series, or periodic value based on selected method) may be defined in which case, if Gain Loss is NaN, the passthrough accounts will compute the Gain Loss slot values.
– Passthrough accounts on a reservoir with storage allowed: Inflow and Slot Inflow must be defined.
– Passthrough accounts on a reservoir with storage not allowed: Slot Inflow must be defined.
– Diversion accounts: Nothing required a priori.
– Storage accounts: Slot Inflow and Gain Loss must be defined.
– Instream flow accounts: Nothing else required.
– If passthrough accounts at the tops of the tributaries’ allocatable flow supply chain can solve (by virtue of having Slot Inflows, these accounts will produce the flow slot values required for the rest of the supply chain to solve before this method is called.
Common Modeling Errors
This list describes some common modeling errors we have seen during the building of test models for testing this method. We have included them for your convenience.
• Adding an object to the model and forgetting to put it into the subbasin.
• The subbasin is disabled. Use Workspace, then Open Computational Subbasin, followed by Subbasin, then Enable Subbasin.
• Model uses the wrong controller. Set your controller to Inline Rulebased Simulation and Accounting.
• Unintended convergence criteria on account slots. Check your convergence criteria.
• Wrong units on account slots. Make sure all the units are what you expect.
• Lags on reaches do not match lags on their accounts.
• Forgetting to set the water type on the supplying account of a water right (at the point of appropriation from the stream). The water type must be set at each point of appropriation from the stream. If you see an Appropriation Request slot value being calculated for a right, but no allocation made to that right (not even an allocation of zero), this is likely to be the reason. Use the visualization tools on the accounting workspace (i.e. Account Groups) to display accounts with a given water type, as in Figure 6.1. Then change any incorrect accounts to the right water type.
• Having more than one account on an object with the allocatable flow supply type. The results are undefined when this is the case. There is one exception, for offstream diversions (see “Linking Accounts” for descriptions), the Diversion object can have multiple passthrough accounts with the allocatable flow supply type.
• User-input data for allocation requests was put into the wrong slot; it should go into Initial Request; not Appropriation Request. The Appropriation Request slot is for outputs of the solution method; this is where the method writes the request as constrained by the state of the system at priority time, i.e., after senior accounts have been satisfied.
• Attempting to use Fill Conservation Pool or Fill Conservation Pool with Diversions method on a Storage Account without setting up the necessary methods and data on the underlying Reservoir object.
• Too many hops from the allocatable flow (stream) to the water right account.
• Supplying a reservoir with project water before the solver is called, thus reducing the appropriation to storage.
• Failing to clear supply chains from non-allocatable water before calling the solver. These allocations may reduce allocations to storage from allocatable water, and they may reduce diversions where diversion capacity is limiting.
• Not providing enough information for all accounts in the subbasin to solve once before the solver rule executes. See the required data in the previous section. This data can be specified by Inputs, Rules, or Object Level Accounting methods. See “Object Level Accounting Methods (OLAMs)” for details. In most models, you probably want to use the following methods:
– Zero Slot Inflows method for most objects. This should be configured to execute at “Beg of the Run”. See “Zero Slot Inflows” for details.
– Copy Slot to Slot Inflows method for local inflow reaches, control points and reservoirs. This should be configured to execute at “Beg of the Run” or beginning of timestep depending on when the local inflows are known. See “Copy Slot to Slot Inflows” for details.
Subordination Viewer
After setting up many subordination relationships between accounts, it can be difficult to keep track of the relationships. The Account Subordination Viewer assists the user in viewing these relationships. This dialog is accessed from the Water Accounts Manager using the System, then Subordinated Rights menu. Figure 6.6 is an example of this dialog. In the list view, the left side shows the dominant accounts, the right side shows the subordinate accounts.
Figure 6.6   
The dialog has three options for displaying the relationships as defined by the radio buttons:
• Show All Water Account Subordination Relationships. Show only those accounts involved in a subordination relationship
• Show All Water Accounts and their Subordinate Accounts. Show all accounts on the left side and their subordinate accounts on the right. Accounts may be repeated.
• Show All Water Accounts and their Dominant Accounts. Show all accounts on the right side and their dominant accounts on the left side. Accounts may be repeated.
At the bottom of the dialog, there are check box options to Show Separate Object / Account Columns for both the left and right sides. The user can either show a column for the Object and another for the Account or one column that lists Object^Account. This option is useful for sorting through accounts or objects. The user can sort the list by any of the columns in this dialog by selecting the column heading.
There is also an option to Show Priority Date Column for both the left and right sides. This allows the user to hide or show the Priority Date column.
Finally, this dialog is strictly a viewer, but using the right-click context menus, the user can Edit or Configure the account or open the Object containing the account. If the subordination relationship changes (outside of this dialog), the user can select the Recompute button to refresh the display.
Solution Algorithm for SolveWaterRights()
This section provides a detailed description of the solution algorithm for the function SolveWaterRights() and SolveWaterRightsWithLags(). SolveWaterRights() can only be called on a subbasin with no lags on the passthrough accounts in the subbasin, and so when it is used, all Local Timestep Offsets are zero, and the solution involves data at the current rules-controller timestep only. When SolveWaterRightsWithLags() is called, Local Timestep Offsets may be greater than zero, and the solution involves data at timesteps which may differ from the current rules-controller timestep.
The rule function’s subbasin argument identifies a computational subbasin with a method selected in the Water Rights Allocation category. The Prior Appropriation method is described here. The method does the following:
1. Determine local timestep of the accounts representing the rights. See “Determine the Local Timesteps of the Rights”) for details.
2. Clone the accounting network. The solver works on this cloned system to solve the problem. See “Cloning” for details.
3. Clear values on supplies that represent allocations from the allocatable flow supply chain. See “Clear Values” for details.
For each water right in priority order:
4. Compute the appropriation request See “Computing Appropriation Requests” for details.
5. Compute allocation that meets the request, constrained by not violating senior rights. See “Computing Appropriation” for details.
6. Create a list of {slot name, value} pairs or a list of {slot name, date-time, value} triplets of allocations that are returned by rule function. See “Return {Slot Name,Value} or {Slot Name, DateTime, Value} List to Rule” for details.
The following sections describe these steps in detail.
Determine the Local Timesteps of the Rights
The local timestep of an account representing a right is defined to be the timestep of the passthrough account representing the appropriation point of the right. For this purpose, the appropriation point of an instream flow right is the sibling passthrough account on the supply chain for which the solver is called. Because the supply chain of interest is not known until run-time (when the predefined rules function SolveWaterRightsWithLags() is called), the local timesteps of the accounts representing the rights must be computed by the solver.
When SolveWaterRights() or SolveWaterRightsWithLags() is called on a subbasin that contains no lags, all the Local Timestep Offsets are zero, and the local timesteps of the rights are the current rules control timestep.
Note:  The entire subbasin must contain no lagged passthrough accounts for this to be true.
The local timestep of the appropriation point is a timestep in the future, defined as current rules-controller timestep + Local Timestep Offset timesteps. All solver operations on the account, its sibling accounts, its appropriation point account and the appropriation point’s siblings, and the underlying simulation object will take place at this local timestep. The Local Timestep Offset slot values of the passthrough accounts have been computed at the beginning of the run. The process of determining these offsets is described below.
At the Beginning of a Run
At the beginning of a run, before the first timestep, an enabled computational subbasin with the Prior Appropriation method selected will compute the Local Timestep Offset slot values for necessary passthrough accounts on objects in the subbasin.
The computation is not system-wide; it's a computation done on the water-rights subbasin, and it's restricted to the part of the subbasin containing rights that appropriate within the subbasin. Thus, only the accounts that figure in the solution for the subbasin are given the offsets. If there's no appropriation at or upstream of a passthrough account on its chain, then the passthrough doesn't need a local timestep and is not reset. If you desire to use the Local Timestep Offset in rules or OLAMs and it is not set by the solver, you should set it yourself.
The computation of the Local Timestep Offset takes place in steps:
1. Compute maximum lag to each passthrough account. This is the largest cumulative lag time (in number-of-timesteps) from any headwater account to the passthrough account, considering only passthrough account lag times (not return flow lags).
2. Compute Lag Distance of the subbasin. The lag distance of the subbasin is the largest maximum lag of all the passthrough accounts in the subbasin; it represents the longest travel time through any supply chain in the subbasin.
3. Compute Local Timestep Offset of the passthrough accounts. The local timestep of an account is the lag distance of the subbasin minus the lag, in timesteps, from the account’s inflow to the end of the subbasin. If lags on supply chains do not match, this can give counter-intuitive Local Timestep Offsets, which can be corrected by adding dummy lagged passthrough accounts at the ends of the supply chains with lower net-lags.
To the right is an example subbasin that shows the Local Timestep Offset computation. In this example, there is a 1 timestep lag at the two yellow reaches (Lag 1TS). Thus, the subbasin’s Lag Distance is 2. The resulting Local Timestep Offset (LTO) are shown.
Note:  LTO at Reach1 and ControlPoint are NaN as they are not needed by the solver.
Figure 6.7   
In the Solver Rule Function
During a call to the solver, the water rights use a local timestep that is determined as follows:
• A Diversion Account uses the local timestep of the passthrough account that represents the (single) appropriation point from the supply chain for which the solver is called. This is an account from which a diversion is made into the diversion account, and has the water type given as an argument to the solver.
• A Storage Account uses the local timestep of the passthrough account representing the (single) appropriation point from the supply chain for which the solver is called. For an in-stream storage right, this is an account from which transfers are made into the storage account, and it has the water type given as an argument to the solver. For an off-stream storage right, this is a passthrough account from which diversions are made into a passthrough account on a Diversion Object, and through which the paper water flows into the off-stream storage account’s Inflow slot.
• An Instream Flow Account uses the local timestep of the sibling passthrough account that has the water type indicating the supply chain for which the solver is called.
Note:  Some Solutions Involve Other Timesteps
A Passthrough Account may have data requirements for timesteps other than its local timestep. Two examples of such cases are when objects have more than one supply chain and the lags on the supply chains differ. In such a model, solving for the Flow slot on an Instream Flow Account requires summation of the inflows across all sibling accounts at the local timestep of the Instream Flow Account for a given Water Type, which may differ from the local timestep of one or more of its sibling accounts. Similarly, solving for the Appropriation Request on a storage account requires summation of the inflows (including transfers in) into all the sibling storage accounts at the local timestep of the storage account whose Appropriation Request is being solved.
Note:  Inasmuch as account methods use data from the underlying simulation object at local (future) timesteps for the accounts, the simulation objects must have dispatched at these future timesteps before the solver is called. An example is the storage account’s Fill Conservation Pool method for computing the Appropriation Request. This method uses the underlying reservoir’s Conservation Pool Initial Empty Space slot value at the storage account’s local timestep. If the local timestep offset of a storage account’s appropriation point is non-zero, the value of the Conservation Pool Initial Empty Space will be needed before it is computed by the beginning-of-timestep phase of the run controller, so the solver will force the computation of the value if needed. The beginning-of-timestep method for the reservoir will not recompute the value once it is defined. The reservoir must have dispatched at the prior timestep to provide a value for Storage, which is needed to compute the Conservation Pool Initial Empty Space.
Cloning
When the rule function is called the first time in a run, it clones all the accounts in the subbasin and their supplies (links). Using the cloned network, the solver can utilize the standard account solution methods without the risk of having side effects on the real accounts, and it can store intermediate results. Each time the solver is invoked by the rule function, current values from the real account slots are copied to the slots on the clones for the set of timesteps necessary to compute the solution. Thus, the rule function abides by the dictate that rules have an all-or-nothing effect and rule functions do not change the state of objects.
As the clones are constructed, tables are created to map donor accounts to their clones. The computational subbasin maintains this table. The cloned accounts reside on the computational subbasin because their underlying objects are not cloned, in the interest of performance. When the solver has to determine which cloned accounts are siblings (their donors reside on the same simulation object), it refers to the mapping.
Clear Values
Each time the rule function is called, in the cloned network it clears all supplies that represent allocations to water rights accounts. Only these supplies are cleared, and not other supplies. As illustrated in Figure 6.7, a call to the solver using the water type “Allocatable Flow” will clear (in the corresponding cloned accounting network) the following supplies:
• Bartlett Reservoir ^ Allocatable Flow to Bartlett Reservoir ^ 1922 Storage
• Bartlett Reservoir ^ Allocatable Flow to Bartlett Reservoir ^ Farmers Project
• Bartlett to Border ^ Allocatable Flow to Green Valley Diversions ^ 1902 Diverters.
• Muddy Reservoir^ Allocatable Flow to Muddy Reservoir ^ Project.
Computing Appropriation Requests
The solver visits each account in priority order: most senior first, and computes appropriation request, then the appropriation. This section describes the computation of the Appropriation Request.
The appropriation request is the amount that the account is legally entitled to ask for. It is the amount that the solver tries to allocate, subject to availability of water not already taken by senior rights. The appropriation request is derived from an initial request, which might be known a priori and taken from the Initial Request slot, or which might have to be computed, based on the state of the network. The account’s method selection in the Initial Request category determines how the initial request is obtained. If the Initial Request slot becomes visible as a result of the method selection and the initial request is computed, its value is stored in the slot. (Whenever the Initial Request slot is visible, so is the Shortage slot.)
Legal and physical constraints may apply to the initial request value, producing a reduced value for the appropriation request, which is stored in the Appropriation Request slot. The legal and physical constraints must reflect the state of the network at in-priority time, namely, after all seniors have received their appropriations.
Computing Appropriation Request from Initial Request
The solver does this in steps:
1. Compute physical constraints applicable to the allocation, based on the state of the cloned network at this time. The solver does this before having the account do anything, because the solver knows about the physical network, which the account does not. The solver determines an upper bound on the allocation due to the physical constraints. Specifically, the means the following:
– Reach Diversion Capacity. If the water right account is a diverter from a reach, the capacity of the diversion structure on the reach limits the diversion. All other diverters from the same reach share this structure, so the upper bound on the Appropriation Request is the Reach object’s Diversion Capacity minus the sum of all existing diversions from the reach passthrough accounts. (Remember that before we got here in the solver, this appropriation was cleared, so its diversion is zero.). The reach Diversion Capacity slot is used to determine the diversion capacity, and if its value is not defined, no diversion capacity limit is applied.
– Reservoir Conservation Pool. If the account is a storage right, the remaining space in the reservoir’s conservation pool limits the Appropriation Request. The inflow required to fill the conservation pool is taken from the underlying simulation object. The reservoir’s slot Conservation Pool Initial Empty Space is computed at the beginning of each timestep as the Inflow volume that would be required to bring the reservoir to the top of conservation pool. It is computed by executing a method on the reservoir “solve inflow given storage and outflow.” The method assumes that outflow is zero and includes evaporation in the mass balance. This flow is used by the solver to determine how much flow it can add, through appropriation, to the total flows into Storage Accounts on the reservoir. All of the reservoirs’ Storage Accounts’ Inflow, Slot Inflow and Transfers In slots are summed; all Transfers Out are subtracted, and the resulting flow is the amount of flow already going into the Storage Accounts. This value is subtracted from the conservation pool initial empty space, to determine an upper bound on the appropriation.
Both of these physical constraints might apply, so the lower of the two upper bounds is chosen.
2. Execute Appropriation Request Methods on Water Right Account. The solver asks the account to compute its appropriation request, applying the upper bounds on the request due to physical constraints: Call the C++ utility method computeDemandForWRA on the account. This method has three steps:
a. First invoke the account’s user-selectable method for determining its initial request as described above, and store this value in a temporary place, Then the upper bound is applied, possibly reducing the request, and the result is again stored in a temporary place.
b. Second, invoke the account’s user-selectable method for Appropriation Request Adjustment, if any (available method is the Return Flow Credit method on Storage Accounts). Pass in the temporary result from above, and store the reduced request again in a temporary place.
c. Invoke the account’s user-selectable methods for legal constraints, including Max Legal Request and Min Bypass.
• Max Legal Request allows the user to enter a value for the Initial Request (on Diversion Accounts only) that is larger than the legal right. This is useful if you are computing the Initial Request from aggregated or historical data. If there is a valid Maximum Request (not NaN), then:
Note:  The reduced request is constrained to be non-negative. See “Max Legal Request”. for details.
• Min Bypass constraints require storage and diversion rights to leave a prescribed flow in the stream at one and only one reference (measurement point), or a percentage of the flow at that reference point, or a combination of absolute flow + percentage. The default reference location is the point of appropriation for the right (a passthrough account on a Reach or Reservoir). An alternate location can be specified, but it must be a Control Point. It can be given in the Bypass Reference Location, which is a list slot that can refer to an object.
The input data needed to compute the MinBypass are:
AbsMinBypass = Absolute minimum required (or zero) to be left in the river at the ref point
FractionAboveMin = Fraction of flow required to be river (or zero), or fraction above the AbsMinBypass if that value is greater than zero.
The Minimum ByPass, the amount required to be left in the stream at the ref point is calculated as:
MinBypass = Min((AbsMinBypass+(TotalFlow-AbsMinBypass)*FractionAboveMin),
TotalFlow)
Where the total flow is the flow at the reference point before the allocation is made.
At the default reference location (Reach or Reservoir), the Total flow is
Total Flow = sum of Available for Appropriation on all passthrough accounts
If the reference point is an alternate location, i.e., a Control Point, the Total Flow is
Total Flow = sum of Outflow of all accounts
The Upper Bound on the Appropriation Request due to Minimum ByPass is
UpperBound(at point of reference) = Total Flow - Minimum Bypass
This is the Upper Bound that the solver applies if the reference location is the default, i.e., the point of appropriation. However, if the reference point is a downstream Control Point, the effects of gain/loss and lag between the reference location and the appropriation point must be taken into account when determining the resulting upper bound on the appropriator’s appropriation request. To do this, the account method makes a callback to the solver, which then pushes onto a stack all the passthrough accounts on the allocatable flow supply chain from the appropriation point to the measurement location. Then it solves upstream by popping accounts from the stack and for each, it routes the upper bound through the account as follows:
UpperBound = UpperBound(from d.s.Account) / (1-GainLossCoeff)
The new upper bound is passed in as input to the solution for the next account popped from the stack. When the stack is empty, the resulting upper bound is returned to the selected method on the appropriating account, which then stores the upper bound in the Temp Min Bypass Constraint (temporary1) slot. Hence, another upper bound has been computed by computeDemandForWRA.
Note:  The minimum bypass constraint applies only to the account with the method selected; it does not in any way affect rights that are junior to this appropriator. If the minimum flow is required to be left in the stream by juniors, all juniors must also have the same method selection and slot values to model the constraint.
3. After these 3 possible constraints on the Appropriation Request have been computed, the solver computes the final Appropriation Request by applying the constraints to the Initial Request and writing the resulting request value to the Appropriation Request slot.
4. If the water right account is an Instream Flow Account on a Control Point object, and it is junior to the controlling date on the solver call, then computeDemandForWRA copies the current Outflow slot value on the allocatable flow supply chain passthrough account on this Control Point into the Available Allocatable Flow slot on the Instream Flow Account.
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 right2, 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 (temporary3).
– 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.
Using Diagnostics with the Solvers
Because the solution to the water rights problem is computed by a computational subbasin, diagnostics pertinent to the solution are available by selecting the computational subbasin that appears as an argument to the predefined RPL function SolveWaterRights() or SolveWaterRightsWithLags().
This selection is made by opening the Diagnostics Manager (Utilities, then Diagnostics Manager), and from there editing settings for Rulebased Simulation. This opens a Rulebased Simulation Diagnostics Configuration dialog. In this dialog, select Show diagnostics for: Run Management, then SimObj. In the same dialog, in a different pane, choose the objects to which these diagnostics apply; this pane is called Show O diagnostics for, and here you select the button marked Select, which opens an object chooser dialog called Select Diagnostics Setting Object. Here you choose the CompObj with the name of the computational subbasin that is used for the solution. Be sure to select Apply or OK in all the dialogs, and be sure to give a destination for your diagnostics in the Diagnostics Manager dialog.
Note:  Enabling diagnostics for the solver produces voluminous output. You should be sure to restrict the date range for diagnostics as much as possible, and it would be best to send diagnostics to a file rather than to the diagnostics output window.

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

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

3 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: 06/03/2019