skip to main content
Objects and Methods : Reach : User Methods : Gain Loss
Gain Loss
This method category is used to model gains and/or losses in the Reach. It is available, as well as all the user methods contained within it, for all Routing methods.
Note:  The equations given for each Gain Loss method may be slightly modified if the Previous Flow Average method is selected in the Apply Gain Loss category.
* None
This is the default method. No calculations are performed and there are no slots associated with this method. It should be used if you do not want to model gains or losses.
* Constant Gain Loss
Used when the gain or loss parameters do not vary with respect to time.
Slots Specific to This Method
 GainLoss
Type: Table
Units: FLOW
Description: represents a given amount of flow that is gained or lost regardless of the flow rate in the reach
Information: A positive number represents a gain while a negative number represents a loss.
I/O: Optional; defaults to 0.0 if not input.
 GainLoss Coeff
Type: Table
Units: DECIMAL
Description: represents a given percentage of flow in the reach that is gained or lost
Information: Must be a number between -1 and 1. For example, a value of -0.1 means that 10% of the flow in the reach is lost. If solving upstream, must be greater than -1.
I/O: Optional; defaults to 0.0 if not input.
 Total GainLoss
Type: Series
Units: FLOW
Description: represents the total amount of flow that is gained or lost in a reach for a given timestep
Information: Applied to the bottom of the reach (it is added to the outflow value calculated from the Routing method).
    
I/O: Output only
* Variable Gain Loss
Used when a time series range of gain or loss parameters is required.
Slots Specific to This Method
 Variable GainLoss
Type: Series
Units: FLOW
Description: represents a given amount of flow that is gained or lost regardless of the flow rate in the reach
Information: A positive number represents a gain while a negative number represents a loss.
I/O: Optional; defeats to 0.0 if not input.
 Variable GainLoss Coeff
Type: Series
Units: DECIMAL
Description: represents a given percentage of flow in the reach that is gained or lost
Information: Must be a number between -1 and 1. For example, a value of -0.1 means that 10% of the flow in the reach is lost. If solving upstream, must be greater than -1.
I/O: Optional; defaults to 0.0 if not input.
 Total GainLoss
Type: Series
Units: FLOW
Description: represents the total amount of flow that is gained or lost in a reach for a given timestep
Information: Applied to the bottom of the reach (it is added to the outflow value calculated from the Routing method).
    
I/O: Output only
* Seasonal Gain Loss Flow Table
Used to calculate the gain/loss parameters based on season and a range of flow rates.
Tip:  The Periodic and Flow based Gain Loss performs similar computations to this method, but is easier to setup. Consider using that method instead!
Slots Specific to This Method
 Date Range
Type: Table
Units: NO UNITS
Description: the actual days of the 366 day year that correspond to the Number of Seasons
Information: Each column of this table corresponds to a particular season and are labeled Season 1 - 12. The two rows labeled 0 and 1 respectively represent the beginning day and ending day of the season column. The allowable range for these inputs is 1 - 366. It is recommended to cover the entire year within the Number of Seasons columns quantified in that slot.
I/O: Required input
 Flow Range
Type: Table
Units: FLOW
Description: the ranges of flow rates corresponding to the Variable GainLoss Coeff Table and Variable GainLoss Table
Information: The number of flow ranges allowed in this table is currently limited to 10.
The columns of this table represent, in ascending order, the maximum flow rate for a specific flow range, starting with 0 as the base. These columns are labeled Flow Range 1 – 10.
Therefore, the first column represents a range of flows from 0 to the value input by the user in the Flow Range 1 column.
The last flow range entered by the user should be a flow rate greater than any anticipated for the simulation; otherwise, a value of 0.0 will be used for flows outside of this range.
It is not necessary to use all 10 columns of this table; use only the columns needed to designate the desired flow ranges.
I/O: Required input
 Number of Season
Type: Scalar
Units: NO UNITS
Description: the number of seasons corresponding to the Variable GainLoss Coeff Table and Variable GainLoss Table
Information: The maximum number of seasons currently allowed in RiverWare is 12.
I/O: Required input
 Variable GainLoss
Type: Series
Units: FLOW
Description: represents a given amount of flow that is gained or lost regardless of the flow rate in the reach
Information: A positive number represents a gain while a negative number represents a loss.
I/O: Optional; if not input, it is obtained from the Variable GainLoss Table.
 Variable GainLoss Coeff
Type: Series
Units: DECIMAL
Description: represents a given percentage of flow in the reach that is gained or lost
Information: Must be a number between -1 and 1. For example, a value of -0.1 means that 10% of the flow in the reach is lost. If solving upstream, must be greater than -1.
I/O: Optional; if not input, it is obtained from the Variable GainLoss Coeff Table.
 Variable GainLoss Coeff Table
Type: Table
Units: TIME
Description: Variable GainLoss Coeff values for each specific Date Range and Flow Range
Information: The columns of the table correspond to the flow ranges defined in Flow Range, and the rows correspond to the seasons defined in Date Range.
I/O: Required input
 Variable GainLoss Table
Type: Table
Units: TIME
Description: Variable GainLoss values for each specific Date Range and Flow Range
Information: The columns of the table correspond to the flow ranges defined in Flow Range, and the rows correspond to the seasons defined in Date Range.
I/O: Required input
 Total GainLoss
Type: Series
Units: FLOW
Description: represents the total amount of flow that is gained or lost in a reach for a given timestep
Information: Applied to the bottom of the reach (it is added to the outflow value calculated from the Routing method).
    
I/O: Output only
* Interpolated Flow Gain Loss
This method is similar to the Seasonal Gain Loss Flow Table method except the data is based on the day of the year and the tables are interpolated to find values for gain-loss and the gain-loss coefficient.
The Periodic and Flow based Gain Loss performs similar computations to this method, but is easier to setup. Consider using that method instead!
Slots Specific to This Method
 Interpolated GainLoss
Type: Series
Units: FLOW
Description: represents a given amount of flow that is gained or lost regardless of the flow rate in the reach
Information: A positive number represents a gain while a negative number represents a loss. It is calculated by double interpolation of the Interpolated GainLoss Table
I/O: Output only
 Interpolated GainLoss Coeff
Type: Series
Units: FRACTION
Description: represents a given percentage of flow in the reach that is gained or lost
Information: Must be a number between -1 and 1. For example, a value of -0.1 means that 10% of the flow in the reach is lost. It is calculated by double interpolation of the Interpolated GainLoss Coeff Table.
I/O: Output only
 Interpolated GainLoss Coeff Table
Type: Table
Units: TIME VS. Flow VS. fraction
Description: A table relating the day of the year, flow rate, and the gain-loss coefficient
Information: Data must be entered in blocks of increasing flow for each given day for the interpolation method to work correctly. January 1 is represented by a 1, February 1 as 32, and so on. Following is an example table.
 
Day of Year
Flow Rate
GainLoss Coeff
1
500
.01
1
550
.02
1
600
.03
32
500
.025
32
550
.03
32
600
.035
60
500
.03
60
550
.035
60
600
.04
I/O: Required input
 Interpolated GainLoss Table
Type: Table
Units: Time vs. flow vs. flow
Description: a table relating the day of the year, the flow rate and the gain-loss value
Information: Data must be entered in blocks of increasing flow for each given day for the interpolation method to work correctly. January 1 is represented by a 1, February 1 as 32, and so on. The table is set up in the same manner as the Interpolated GainLoss Coeff Table (shown above).
I/O: Required input
 Total GainLoss
Type: Series
Units: FLOW
Description: represents the total amount of flow that is gained or lost in a reach for a given timestep
Information: Applied to the bottom of the reach (it is added to the outflow value calculated from the Routing method).
I/O: Output only
Method Details  
A 3‑D interpolation method is used to calculate a value for Interpolated GainLoss and Interpolated GainLoss Coeff using the Interpolated GainLoss Table and Interpolated GainLoss Coeff Table, respectively. Once these values are calculated Total GainLoss is set as follows:
    
* Base Plus Fractional Loss
This method is used to model loss in a reach; it does not allow gain. Loss is calculated as base flow rate plus a proportion of the flow above the base. Loss is limited to be less than a maximum value. This method will be available for all Routing methods except Time Lag routing.
Slots Specific to This Method
 Base Loss
Type: Periodic
Units: Time vs Flow
Description: Represents an amount of flow that is lost regardless of the flow rate in the reach. The method will limit the total loss to be less than or equal to the flow in the reach.
Information: A positive number represents a loss. A negative number results in an error.
I/O: Required input
 Loss Fraction above Base
Type: Periodic
Units: Time vs Decimal
Description: This slot represents a fraction of the flow above the Base Loss that will be lost
Information: A positive number represents a loss; the value must be between 0 and 1 or an error is issued.
I/O: Required input
 Maximum Loss
Type: Scalar
Units: FLOW
Description: The maximum loss that can occur from the reach
Information: If not input, no maximum is used
I/O: Optional Input
 Total GainLoss
Type: Series
Units: FLOW
Description: Represents the total amount of flow that is gained or lost in a reach for a given timestep
Information: A positive number represents a gain, a negative number represents a loss. The Total GainLoss is applied to the bottom of the reach (it is added to the outflow value calculated from the Routing method). In this method, a loss is represented by a negative number.
I/O: Output only
Method Details 
At the beginning of the method, the values for Base Loss and the Loss Fraction above Base are taken from the periodic slots and checked. As is typical with periodic slots, these slots can be configured to either lookup or interpolate. If either is invalid, the run terminates with an error. If the Base Loss is less than zero, the run terminates with an error. If the Loss Fraction above Base is less than 0 or greater than 1, the run terminates with an error.
On a reach, the Total GainLoss slot is used by other GainLoss methods. As a result, this method follows the same convention where a negative Total GainLoss represents a loss. Also, the flow used by the method is the flow in the reach after the routing has occurred. Thus, the Total GainLoss is the base loss plus the fractional loss associated with the flow above the base. Because the flow could be less than the base, the following formula is necessary to calculate the loss:
    
If Maximum Loss is NaN, then the Total GainLoss is set equal to the negative of the tempLoss value.
    
Otherwise, there is a valid Maximum Loss and the Total GainLoss is then set as follows:
    
* Periodic Gain Loss
This method is used to model gain and/or loss in a reach. The gain and loss values are entered as periodic data for a given time range. Gains are entered as positive values and losses are entered as negative values. This method will be available for all Routing methods except Time Lag routing.
Slots Specific to This Method
 Periodic GainLoss
Type: Periodic
Units: Time vs Flow
Description: Represents an amount of flow that is gained or lost regardless of the flow rate in the reach.
Information: A positive number represents a gain. A negative number results in a loss.
I/O: Required input
 Total GainLoss
Type: Series
Units: FLOW
Description: Represents the total amount of flow that is gained or lost in a reach for a given timestep
Information: A positive number represents a gain, a negative number represents a loss. The Total GainLoss is applied to the bottom of the reach (it is added to the outflow value calculated from the Routing method). In this method, a loss is represented by a negative number.
I/O: Output only
Method Details 
At the beginning of the method, the value for Periodic GainLoss is taken from the periodic slot and checked. As is typical with periodic slots, this slot can be configured to either lookup or interpolate. If the value is invalid, the run terminates with an error.
This method follows the same convention as other GainLoss methods where a positive Total GainLoss represents a gain.
    
* Periodic and Flow based Gain Loss
This method models Gain and Loss as a variable flow rate and fraction of the routed flow. Both the flow rate and the fraction are based on a date and flow rate, or could be specified by input or rules
Slots Specific to This Method
 Periodic Gain Loss Table
Type: Periodic Slot with Numeric Header
Units: Header = Flow, Values = Flow
Description: The matrix that describes the amount of flow that should be gained or lost.
Information: This table has a column map, which means that each column has an associated numerical value (with units) displayed as the column label.
Columns are added and deleted from this table using the Column menu. User units, scale, type, and precision for the column map (that is, the column heading values) are defined in the unit scheme for Flow unit types. Column map values are set by selecting Column, then Set Column Value.
hen a column value is changed, the columns reorder to ensure the column values are increasing, from left to right. The left-most set of values should represent the minimum flow in the Reach. The right-most set of values should represent the largest flow expected. Values are interpolated across columns.
The configuration of the slot controls how values are accessed across rows (interpolate or lookup). Seen Figure 23.1 for a sample. Extra columns have been added to look up across flow ranges.
I/O: Required input
Figure 23.1  Screenshot of a sample Periodic Gain Loss Table
 Periodic Gain Loss Coeff Table
Type: Periodic Slot with Numeric Header
Units: Header = Flow, Values = Fraction
Description: The matrix defining the percentage of the routed flow that should be gained or lost.
Information: This table has a column map, which means that each column has an associated numerical value (with units) displayed as the column label.
Columns are added and deleted from this table using the Column menu. User units, scale, type, and precision for the column map (that is, the column heading values) are defined in the unit scheme for Flow unit types. Column map values are set by selecting Column, then Set Column Value.
When a column value is changed, the columns reorder to ensure the column values are increasing, from left to right. The left-most set of values should represent the minimum flow in the Reach. The right-most set of values should represent the largest flow expected. Values are interpolated across columns.
The configuration of the slot controls how values are accessed across rows (interpolate or lookup). See Figure 23.2 for a sample. Extra columns have not been added to allow it to interpolate across flow ranges.
I/O: Required input
Figure 23.2  Screenshot of a sample Periodic Gain Loss Coeff Table
 Variable GainLoss
Type: Series
Units: FLOW
Description: represents a given amount of flow that is gained or lost regardless of the flow rate in the reach
Information: A positive number represents a gain while a negative number represents a loss.
I/O: Optional; can be input if needed. More likely it is obtained from the Periodic GainLoss Table.
 Variable GainLoss Coeff
Type: Series
Units: FRACTION
Description: represents a given percentage of flow in the reach that is gained or lost
Information: Should be a number between -1 and 1. For example, a value of -0.1 means that 10% of the flow in the reach is lost. If solving upstream, it must be greater than -1.
I/O: Optional; can be input if needed. More likely it is obtained from the Periodic GainLoss Coeff Table.
 Total GainLoss
Type: Series
Units: FLOW
Description: represents the total amount of flow that is gained (+value) or lost (- value) in a reach for a given timestep
Information: Applied to the bottom of the reach (it is added to the outflow value calculated from the Routing method).
I/O: Output only
Method Details  
The method computes the Total Gain Loss as follows:
The flow to use is provided by the routing method as the “Routed Flow.”
    flow = RoutedFlow
    Variable Gain Loss = Periodic Gain Loss Table [timestep, flow]
    Variable Gain Loss Coeff = Periodic Gain Loss Coeff Table [timestep, flow]
    Total Gain Loss = Variable Gain Loss Coeff * flow + Variable Gain Loss
Note:  When solving upstream, the computation is iterative as the gain loss depends on the upstream routed flow, which is what is what is being computed. Convergence is defined on the Outflow slot. Max iterations is based on the simulation max iterations.
The Total GainLoss is returned to the dispatch method where it is used in the mass computation. This method follows the same convention as other GainLoss methods where a positive Total GainLoss represents a gain.
Revised: 07/09/2023