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 (that is, 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 (that is, 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 (that is, 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.
• Having supplies that enter or leave the allocation subbasin but contain allocatable water. Use the diagnostics described in Using Diagnostics with the Solvers to print messages about these supplies when the subbasin is cloned.
• 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; that is,, 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 Screenshot of the Account Subordination Viewer
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.
Revised: 07/03/2024