skip to main content
An exchange is a RiverWare utility that models a special relationship amongst a set of supplies.
Exchange Description
An exchange is defined by the user to keep track of debts when (paper) water is borrowed from one account and then later returned (if necessary). Borrowed water is represented by a transfer from one account to another through a supply. Repayment of the debt is represented by one or more different supplies.
An exchange is a utility used to track the borrow and payback of water from one account to another.
An exchange in RiverWare only models relationships among entities in the accounting network, In as much as a model uses an accounting network to model ownership and movement of water in the physical network, exchanges can be used to represent physical transfers also.
For example, an exchange can be used to represent the following.
• A transfer of water. Water must be released from reservoir A due to maintenance concerns and the water is stored in downstream reservoir B. To pay back the exchange, reservoir B pumps water to local irrigators that are in reservoir A’s service area.
• A change of ownership. Water in a reservoir is transferred from owner 1 to owner 2 but no physical release was made. The exchange may or may not be paid back.
• In-lieu of release. Reservoir A is obligated to make a release for downstream diverters. Instead it is negotiated that parallel Reservoir B will make the release and satisfy both the demand and some other purpose like power production. The exchange is paid back by reversing the releases, Reservoir A releases when there is no power demand but minimum flows that would have come out of Reservoir B must be met. These types of exchanges are typically negotiated to try to provide multiple benefits by releasing from the most appropriate reservoir, not necessarily the reservoir that is supposed to release.
Exchange Components
To represent the location and/or quantity of borrowed water, an exchange contains a series slot called either “Borrow” or “Input Borrow”, depending on how the exchange is configured (described in detail below). Regardless of the slot name, this slot represents the amounts of paper water borrowed.
The exchange offers two different ways to monitor the resulting debt (unpaid balance). The first way is required, the second is optional.
First, the exchange must have one or more payback supplies, each of which contributes to the payback, thereby reducing the entire debt. The exchange keeps track of the entire remaining debt (considering all payback sources) in a slot called “Source Balance”, described in detail below. Each payback source may have a loss associated with it. For each payback, the exchange keeps a slot to monitor the debt that payback source would have to pay to resolve the entire remaining debt by itself, taking into account the loss associated with that payback source.
Second, the exchange may (optionally, and in addition to monitoring payback sources) monitor the paper water flowing through a single Payback Destination Supply. No loss may be associated with this supply. The exchange keeps track of the entire remaining debt according to this scheme with a slot called “Destination Balance”. Configuring the exchange to use this monitoring scheme is described in detail below.
Following is a description of the components to the exchange including the Borrow, Payback Source Demand and Payback Destination Supply. The Exchange can be tracked by two separate balance slots, the source balance and the destination balance. The source balance keeps track of the borrowed water and the debt (including a legal loss term) that must be repaid through the Payback Source Demands. Alternatively, the exchange can be tracked using the Destination Balance. This tracks the borrowed water and water that arrives at the Payback Destination. This is a single supply and no loss is allowed.
To make an exchange, the user must specify the supply and give it a value (using either input, rules, object level method) or input the amount of water that is borrowed. This is called the Borrow.
A supply (or user input) representing the water that initiates the exchange.
In the exchange balance, a slot is added called the Borrow (or Input Borrow) slot:
Borrow Supply or Input Borrow Supply
Type: Series Slot
Units: volume
Alternate Units: NA
Description: The supply that represents the water borrowed as part of an exchange. This is typically a reference to a supply in the model. In that case, the exchange displays the slot as “Borrow Supply.” It can also be configured such that the borrow amount is input directly into the exchange balance dialog. In that case, the slot is called “Input Borrow Supply” and is created on the exchange object to store the user inputs.
I/O: Input or set by a rule
To keep track of the total debt at each timestep based on payback sources, the exchange maintains a slot called Exchange Source Balance. To continue the example, the statement you receive from the bank each month shows the balance remaining on your house loan. This is the Source Balance. If you take out a second mortgage to remodel your house (i.e. borrow more), your source balance will increase. If you make payments on the house the source balance decreases. The Source Balance is calculated as:
Source Balance
Type: Series Slot
Units: Volume
Alternate Units: NA
Description: The Source Balance is the previous Source Balance plus the amount in the Borrow Supply minus the sum of any Payback Source Demands (including loss).
I/O: Exchange Solution
An exchange is paid off through paybacks represented by one or more supplies. The various payback supplies are called Payback Source Demands. The nomenclature demand can be confusing to many users. Conceptually, a supply is water entering an account (i.e. supplying that account with water); a demand is water exiting an account (i.e. water is demanded from that account). In RiverWare, the term demand refers to the receiving/downstream end. Supply refers to the supplying/giving/upstream end as well as to the slot that propagates to both ends, or to the combined supply/demand pair. As a result, RiverWare typically refer to all transfers between accounts as supplies. The Payback Source Demand is one of the few places in RiverWare where the transfer is called a demand. Each Payback Source Demand may have a loss associated with it, which is a value computed from a loss coefficient associated with the payback source.
Payback source Demand
Payback Source Demands (i.e. Supplies) are one or more supplies where an exchange may be considered to be paid back. Each Payback Source can have a legal loss associated with it.
For each Payback Source Demand, a slot is added to the exchange that represents the debt that would have to be paid back to fully satisfy the source balance
Debt (for each supply specified)
Type: Series Slot
Units: Volume
Alternate Units: na
Description: For each payback source, the exchange maintains a slot Debt to keep track of a debt associated with that payback source. It is the amount that would be necessary in the given supply to pay off the total debt including any loss.
I/O: Exchange Solution
To keep track of the total debt at each timestep based on a destination payback supply, the user selects a Payback Destination Supply.
Payback Destination Supply
A single supply where the exchange payback may be monitored. No loss is associated with this supply.
When the user selects a destination, the Destination Balance slot is added to the exchange and is calculated as:
Destination Balance
Type: Series Slot
Units: Volume
Alternate Units: na
Description: The Destination Balance is the previous Destination Balance plus the value in the Borrow Supply minus the value in the Payback Destination Supply.
I/O: Exchange Solution
An exchange will re-solve whenever a new value is set on its borrow, payback source(s), or destination payback supplies. The borrow and payback source(s) values may be set via user input or rules. Borrow values may be set on a supply or as a user input on a slot on the exchange object (user input demand). The effects of each new value are listed below:
• A value on a supply or user input slot registered as a Borrow will increase the debt on that exchange; Source Balance, Destination Balance, and the Debt (for each payback) will increase.
• Releases from a supply registered as a Payback Source Demand on an exchange will reduce the debt on the exchange; Source Balance and the Debt at each payback will decrease.
• Releases arriving at a Destination will reduce the Destination Payback Balance. This is NOT the same as reducing the debt.
Accessing Exchanges through RPL
The debt of a given exchange, if paid through a certain payback source, is the value of the debt slot on that payback. Two RPL functions enable users to access the debts:
• GetPaybackDebt (STRING SupplyName, DATETIME date)
The SupplyName argument is a string representing the Source Payback Demand. The date argument is the date at which to get the payback debt. The function gets the value of the debt associated with the given Payback Source Demand at the given timestep.
• GetObjectDebt (OBJECT object, DATETIME date)
This function evaluates to the sum of the debts to all accounting exchanges which may be paid by supplies on the given object at the given timestep. If there are no exchange paybacks on the given object, the debt is zero.
Exchange Examples
Example 5.1 and Example 5.2 illustrate exchanges and how they are defined in RiverWare.
Example 5.1 is a simple problem but explores the configuration of the supplies. Example 5.2 is more realistic and presents alternative configurations for the exchange.
Example 5.1   
Two water owners, Harry and Otto own water in two different reservoirs, Green Lake and Blue Lake. On each of the reservoirs are accounts Harry and Otto. At Blue lake, Otto owns a dock for fishing and wishes to keep the reservoir as high as possible during the summer. As a result, he has agreed to borrow water from Harry during the summer for fishing. He will pay back any water borrowed by transferring water at Green lake from Otto to Harry. Harry loves this idea because he is an expert kayaker and now controls more water in Green Lake which he can release directly into his favorite kayaking reach, GreenRiver. Let’s set up this exchange:
We establish a supply transferring from Blue^Harry to Blue^Otto to represent Otto borrowing water from Harry at Blue Lake. This supply will be called Borrow. Otto returns water to Harry at Green Lake; this is represented by a supply called Payback, which will be a transfer from Green^Otto to Green^Harry. All the water that flows through Borrow at time t increases Otto’s debt at time t, and all that flowing through Payback decreases the debt at time t. In the exchange manager, Borrow is the Borrow Supply and Payback is the one and only Payback Source Demand.
Returning to the example above, Otto decides that Kayaking isn’t for him but instead wants to innertube on the calm BlueRiver downstream of both reservoirs. We still wish to keep track of the debt at Blue Lake, but perhaps he does not want the debt to be considered repaid until the water reaches the Blue River downstream of both lakes. To model this, we choose “Turquoise RiverFlows to BlueRiver RiverFlows” as the Payback Destination Supply. Water flowing through this supply represents the total water paid back, and the balance at time t is maintained in the exchange slot Destination Balance. In this way, we see that any water released out of either Blue or Green would repay the exchange.
Figure 5.1 shows the layout of this accounting system and the appropriate supplies.
Figure 5.1   
Example 5.2   
In this example, we first describe the physical conditions, background, and policy that motivate this exchange. Then we describe how to define this exchange in RiverWare.
The following diagram shows a layout of a basin consisting of two reservoirs. TroutLake was built specifically to make releases to meet Fish Targets at the CriticalPoint control point for endangered species. All of the water in TroutLake is stored in the Fish storage account. A chain of passthrough accounts, also named Fish, was created to move the water from the Fish storage account to the Fish instream flow account on the CriticalPoint control point.
DeepLake was built and is owned by an irrigation company. Water stored in this reservoir is released to meet farmer’s demands at the IrrigationCompany water user. To represent this, a storage account name FarmerA was created in DeepLake and passthrough accounts were created to move the water from that account to the FarmerA account on the IrrigationCompany water user. This example shows a small sample of the accounts in this basin. Likely there are other farmer accounts on DeepLake and on the IrrigationCompany. In addition, there is likely policy in the basin to simulate other objectives like flood control. This example simplifies the policy but it is good to be aware that this exchange must fit into the other operating objectives.
TroutLake is a relatively small compared to DeepLake. During the hot summer months, TroutLake often does not have storage or release capacity to entirely meet the required fish flows at the CriticalPoint. To maintain adequate habitat for the endangered fish species, an exchange agreement was negotiated to between the Fish and FarmerA accounts to provide more water for the fish. The agreement states that if TroutLake is low and cannot meet Fish Targets, FarmerA will release water from DeepLake that will be allowed to flow to the CriticalPoint. The balance of the exchange will be repaid, including a legal loss of 5%, by releasing additional water from the Fish account at TroutLake that can then be diverted to FarmerA. Now we will define how this exchange will be configured in RiverWare. First, let’s create and define a borrow supply. The borrow supply must allow FarmerA water to release to the Fish account. This supply goes from DeepLake^FarmerA.Outflow to Confluence^Fish.Inflow. This is the borrow supply.
We will go through two cases. One with just a source payback and the other with a source payback and destination payback.
Figure 5.2   
In the first configuration, the exchange is paid back by releasing additional water from the Fish account that can be diverted to FarmerA. We must create a supply from DiversionReach^Fish.Diversion to IrrigationCompany^FarmerA.Diversion. This is the payback supply. Figure 5.3 shows this connection. In this way, water can be borrowed from FarmerA and allowed to flow to the Fish instream flow account. It can also be paid back by releasing water from TroutLake through the series of Fish accounts, then diverted to the FarmerA account on the water user. Rules or user inputs will be used to set values on these exchanges. In this configuration, water is paid back only when it is diverted to FarmerA. If there is a legal loss, this supply would be defined as the Payback Source Demand. If there is no loss, this could be defined as a Destination Payback. Until water reaches this diversion supply, the paper water still belongs to the Fish account and will incur any Fish losses in LongReach.
Figure 5.3   
In the second configuration, the Borrow supply remains the same but we will create a separate FarmerA passthrough account on the LongReach and supplies connecting it to the other FarmerA passthrough accounts. The supply connecting TroutLake^Fish.Outflow to LongReach^FarmerA.Inflow is the Payback Source Demand. A second diversion supply will then be created from DiversionReach^FarmerA.Diversion to IrrigationCompany^FarmerA.Diversion. Now there are two supplies connecting these two accounts. This new supply is the Payback Destination Supply. The following diagram shows these new accounts and supplies.
In this configuration, once water is released from the Fish account to repay the exchange, it becomes FarmerA water and may or may not incur loss (depending on policy) in the Long Reach. By defining a Legal Loss, on this Payback Source Demand, we can specify that more water is required to repay the exchange than was borrowed, i.e legal loss was incurred. We can also define the Payback Destination Supply and then the exchange will track the Destination Balance in addition to the debt remaining from Payback Sources. Rules can then look at the Source Balance, Payback Debt, and Destination Balance to determine how much water to release to repay the debt
Figure 5.4   
Exchange User Interface
Following is a description of the exchange user interface.
Exchanges Manager
Exchanges are created through the Exchanges Manager dialog. This is accessed from the workspace through the Accounting, then Exchanges Manager. It can also be accessed from other locations such as the accounts manager and supplies manager. Figure 5.5 shows the Exchange Manager with one exchange defined. It lists each exchange and the Borrow supply (or user input) associated with that exchange. Items in this list can be sorted by selecting either column heading.
Figure 5.5   
To edit data (or view) for an existing exchange, highlight the exchange and select Edit. This brings up the Exchange Balance dialog. We will explore this later. To create a new exchange select New and a blank Exchange Configuration dialog will open. To modify an existing exchange, select Configure to open the Exchange Configuration dialog.
Exchange Configuration Dialog
The Exchange Configuration consists of four areas: Borrow Supply, Payback Destination Supply, Payback Sources and Units. On the first line, the user can enter an Exchange Name in the text field.
The Borrow Supply can be specified using the radio buttons to select either that the user will use the Select button or that the user will Input Borrowed Amounts. If the Select option is used, the text field becomes active. The user can either type in the supply name (not recommended) or select the Select button to select the supply using the standard selection mechanism.
The user can then configure the Payback Destination Supply. To reiterate, either zero or one Payback Destination Supply is allowed. The user can select whether to Select Destination or have No Destination. Again, if the user chooses to Select Destination, the user can either type in the supply name (not recommended) or select the Select button to select the supply using the standard selection mechanism.
The third area, Payback Sources, allows the user to specify the Payback Sources which consist of one or more supplies and legal loss associated with each supply. To add a Payback Source, select the Add button and select the supply. Then enter the Legal Loss using a click-pause-click action to make the text field editable. It will default to 0.0 if not input. To replace (re-select) any of the existing supplies, first select the supply from the list, then select Modify to select a new supply or type in a new legal loss. Use the Remove button to delete the selected supply from the exchange.
Click OK or Apply to confirm the changes.
Exchange Balance Dialog
The Exchange Balance dialog shows the slots associated with the exchange. Depending on the exchange configuration, different slots will be shown. Figure 5.6 shows the Exchange Balance dialog with defined Borrow Supplies, Destination Payback Supplies, and Source Balance, Destination Balance, the Payback Debt, and the Payback Supply.
Figure 5.6   
Each column represents a series slot. Those labeled as “Supply” reference a supply in the model. Those labeled as “Balance” or “Debt” are the exchange specific slots. The column labels provide a reference to the actual supplies. The key in the lower part of the window displays the full name of the supply. This allows the columns to remain relatively narrow but still have descriptive names associated with each component. The dialog has similar features to other accounting dialogs, including the scroll button, Plot button, and Show Slots menu. There is also the ability to hide or compress repeated values, a specified value, or NaNs. See “Series Display Compression” in User Interface for details about Series Display Compression. There is also the summary area where statistical information can be obtained for the highlighted selection.
In Figure 5.6, we see that when water goes through the Borrow Supply, the Exchange Source Balance increases as does the Exchange Destination Balance. The Payback Debt for each payback source also increases which includes the legal loss term. The debt is always larger than equal to the source balance. As water passes through the Destination Supply, the Destination Balance decreases. As water passes through the Payback Source Demand (shown as Payback-1 in the figure), the Source Balance and Debt decrease.
Typically the values in the Exchange Balance are read-only; any edits to input data must be made directly on the borrow or payback supplies. The Exchange Balance is a view of the data in those supplies. Also, any of the Balance or Debt columns are always read-only as they are outputs from the solution of the exchange equations.
The one exception to the read-only constraint is when the user has configured the exchange to “Input Borrowed Amounts” in the exchange configuration. Then, the borrow supply lives on the exchange, is labeled “Input Borrow” and is directly editable from the Exchange Balance dialog.
Note:  When first created, the Input Borrow is empty, so the user must select the Show All menu to show this slot. Also remember that any Input Borrow amounts are always entered as a volume.
Revised: 06/03/2019