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.
Exchange 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.
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
Links: No
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 (that is, 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
Links: No
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 (that is, supplying that account with water); a demand is water exiting an account (that is, 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 (that is, 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
Links: No
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
Links: No
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.
Revised: 07/05/2022