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; that is,, 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 computational subbasin is described in more detail About Computational Subbasins in Objects and Methods.
Warning: A model can have multiple water rights computational subbasins only if the objects are hydraulically disconnected, for example an upstream subbasin and downstream subbasin or two parallel subbasins. Also, only one subbasin and one supply chain can be used on a set of objects. Multiple supply chains with different water types or different water rights subbasins on the same objects isn’t allowed, even with separate calls to the SolveWaterRights functions.
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, 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; that is,, 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.
Revised: 01/11/2023