skip to main content
User Interface
This document describes the following uses of units in RiverWare:
• Standard, internal units in which calculations are performed
• Unit Schemes which allow you to define one or more systems of display units
• A utility to convert the units of values
Standard Units
In RiverWare, all calculations are performed in standard or internal units. Table 3.1 lists the internal (standard) units for some common unit types.
Table 3.1   
Unit Type
RiverWare Internal Unit
Display Value
meter3 / second
megawatt hour
meter / second
gram / meter3
The standard units for all unit types can be viewed in the Unit List dialog. From the Units menu in the main RiverWare workspace, select List Available Units. At the bottom left of the resulting Units List dialog, there is a check box to Show only units that are present on the workspace. Uncheck the box to show all available unit types. The first unit listed for each unit type is the standard unit for that type.
Display Units
You can configure any value in RiverWare to be displayed in units other than the standard units. The display units are user-selectable for each set of data. They may be changed at any time through the Unit Scheme (see Unit Schemes), or for an individual slot, through the Slot Configuration menu; see “Configure Slot Dialog”.
When data is entered or imported, the values should be in the slot’s display units. This means that you must change the display units to match the units of incoming data before entering or importing data.
You can view all available display units in RiverWare along with their conversion factors in the Units List dialog; see Figure 3.1. From the Units menu in the main RiverWare workspace, select List Available Units. All of the available display units are shown on the Display Units tab. At the bottom left of the Units List dialog, there is a check box to Show only units that are present on the workspace. Uncheck the box to show all available units and their conversion factors. The Units List dialog also has a RPL Units tab that shows all of the unit components that can be used to construct units in RPL expressions. For more details on RPL units, see “Units in RPL” in RiverWare Policy Language (RPL). You can also view the conversion factors for units by using the Unit Converter; see Unit Converter Dialog for details.
Figure 3.1  Units List dialog
Unit Schemes
A Unit Scheme describes how you want to display numeric slot values in terms of the following display attributes:
• Units
• Scale
• Precision
• Format
Figure 3.2 identifies the attributes.
Figure 3.2   
Note:  Schemes provide settings for Units, Scale, Format, and Precision. In this document these are collectively referred to as units. For example, it says that the slot units are displayed using the settings and rules for the scheme. Remember, this also includes scale, format and precision even though it is not explicitly written.
You can view and edit the Unit Scheme definitions and easily switch between the Unit Scheme in use. For example, you may wish to develop a model using cfs, acre-feet, and ft, but you wish to show the model result to international stakeholders who wish to see results in m3/year, 1000 m3, and m. Create two Unit Schemes with the desired user units and easily toggle between the two schemes depending on who is viewing the model.
Following are some features of Unit Schemes.
• The currently active unit scheme is used everywhere a slot value is displayed, at all times. This includes the slots, objects, and accounts interface, SCTs, diagnostics, RPL debugging, and output devices like plots and model reports.
• Every unit scheme is complete for every Unit Type. It describes how every slot value shall be displayed. Associated with every valid unit type is the desired set of display attributes called a Unit Type Rule.
• You can create exceptions to the Unit Type Rules to display different attributes for the following:
– A slot with the given name. These are called Slot Name Exceptions and apply to slots on any object or a specific object type.
– A specific object and slot (and column if necessary). This is called a Slot Exception.
• When a model saved with RiverWare version 6.3 or earlier is loaded, a transitional unit scheme is created which replicates the display of slot values in the prior version.
• Each DMI continues to use the specifications contained within the DMI to interpret the units and scale of input values and to determine the desired units, scale, precision and format of output values. When the DMI does not contain such a specification, the currently active scheme will be used, though the user will be warned that this is happening and encouraged to specify the units within the DMI.
Frequently Asked Questions (FAQs)
Figure 3.3 lists frequently asked questions (FAQs) and short answers, followed by links to more information.
Table 3.2   
What are Unit Schemes?
A Unit Scheme describes how you want to display numeric slot values in terms of four display attributes: units, scale, precision, and format.
To what parts of RiverWare do they apply?
Anywhere a numeric value is displayed. This includes, slots, objects, account, SCT, plots, output devices, reports, RPL debugger, diagnostics
How do I switch between schemes?
From the workspace, open the Unit Scheme Manager using the Units, then Unit Scheme Manager. From the Unit Scheme pulldown menu, choose a new scheme and click Activate
What if I want one slot to show units that are different than the rest of the scheme?
You can create exceptions to the scheme that apply to a group of slots of the same name or one specific slot.
Can I change the display units from the slot dialog itself?
Yes, when you change the units from a slot, you automatically create a Slot Exception.
Can I show Flow slots as a Volume and vice versa?
Yes, for flow series slots, the slot or SCT dialog has a Flow/Vol button on the toolbar. Some relevant volume slots, like Evaporation, also show the button. You can create slot name unit scheme exceptions for both the Flow and Volume unit type for a particular slot, if desired.
How do I fix a slot’s units, without changing the displayed values?
Change the units from the Open Slot and choose to Repair incorrect Units.
I’m starting a new model, how do I set up the units I want?
Create a new scheme with the units you want. It is easy to create or change this scheme at any time, so there is little need to do it as the first step in model building.
Will existing models (saved before 6.3) have the same units?
Yes, when an older model is loaded and it has no scheme, a transitional scheme is created to represent the units used in the saved model.
If I change the units or activate a different scheme, will I get the same results?
In general, RiverWare does all calculation in internal units, changing the scheme will not affect underlying results. There are a few methods that depend on slot units. Click the link for more information.
Do some computations or methods depend on specific units?
Can I share schemes between two models?
Yes, Export the scheme from one model and Import it into another model.
Working With Unit Schemes
Figure 3.3 identifies the main areas of the Unit Scheme Manager.
Figure 3.3   
Creating and Deleting
Create a New, Duplicate, Rename or Delete the current scheme from the File menu. When creating a new scheme, renaming or duplicating an existing scheme, the Add New Unit Scheme dialog will open where you can specify the new name.
To delete a scheme, choose the desired scheme from the pulldown and then choose File, then Delete Scheme.
A scheme must be activated before any of the display attributes change. Activate a scheme by choosing the desired scheme and clicking the Activate button.
Once you activate a scheme, all slot values are then shown using the attribute settings and the rules for that scheme. In the Unit Scheme Manager, the rows are shown in a pink color. An scheme that is not active is shown in a green color.
Values are always converted to the new units. See Repairing Incorrect Units of Slot Values for instructions on fixing values that were imported into a slot with the incorrect display units.
Sharing Schemes Using Import and Export
Schemes from one model can be exported to a file, and then imported into another model. Select the desired scheme and then perform the following steps.
1. Use the File, then Export menu to export the scheme. Specify a file name.
2. In the second model, open the Unit Scheme Manager and choose the File, then Import menu. Choose the file specified.
The exported file is saved as an XML representation of the unit scheme.
Defining a Scheme
This section shows how to actually define the scheme. It consists of two parts, editing the attributes (setting the units, scale, precision, format) and creating exceptions to the Unit Type rule.
Editing Attributes
The table view shows each of the Unit Types in RiverWare. Those not in use in the model are hidden when the Show only types that are present on the workspace toggle is checked. You can show them by clearing the box.
Each row in the table then represents a Unit Type Rule. That is, for that unit type, it defines how numeric values will be displayed. The attributes are not show explicitly, but are shown through the Format Example. E.g., 21.1 1000 cfs indicates a flow unit type will have a unit of cfs, a scale of 1000, a format of float, and a precision of 1.
Use the following steps to set an attribute.
1. Select a row in the tree view.
2. Edit one of the four attributes.
Changes are applied immediately.
Creating Exceptions
You may wish to have a slot display units that are different than other slots of that same Unit Type. For example, you maw wish to show your Reservoir.Evaporation in “acre-ft” while displaying Storages and other VOLUMES in “1000 acre-feet”. Or more specifically, maybe you want to show the Evaporation for FlatReservoir.Evaporation in 100 acre-feet. Both of these are possible by creating Exceptions to the Unit Type rule. You can create exceptions to the Unit Type Rules in the Add Exception portion of the dialog at the bottom.
Slot Name Exceptions
Each exception applies to a specific Unit Type. Choose that first from the pulldown list. Specify a slot name and optionally the object type. These rules apply to slots on any object or a specific object type. Enter or choose a slot name using the chooser. Remember, this is any slot that matches that name on that type of object. Once specified, click the green Plus button to add it to the scheme .
Following are examples of Slot Name Exceptions:
• <Any Object>.Evaporation
• <Reservoir>.Storage
• <Reach>.LagTime
• <Storage Reservoir>.Elevation Volume Table col=0
• <Storage Account>.Gain Loss
Slot Exception
Each exception applies to a specific Unit Type. Choose that first from the pulldown list. Specify a particular object.slot (and column if necessary). Type in or choose one or more fully specified slot (and column) using the chooser. Remember, this is a specific slot (or column on that slot). Once specified, click the green Plus button to add it to the scheme . If you selected multiple slots, a slot exception is created for each slot.
Following are examples of Slot Name Exceptions:
• Mead.Evaporation
• DreamLake.Seasonal Inflow Coefficients col = 2
• BigReservoir^City.Storage
Note:  When you configure an individual slot, you are actually creating a Slot Exception for that slot within the currently active Unit Scheme; see “Configure Slot Dialog” for details. After making the change in the slot, you can go to the unit scheme and see that exception.
Adding the two exception described at the beginning of this section to the scheme would add rows to the table as sub items to the specified Unit Type Rule (in this case it was Volume). You then set the attributes for each of the rules; see Editing Attributes for details. Figure 3.4 shows the result.
Note:  When multiple rules apply to a slot, the most specific rule applies.
Figure 3.4   
Updating Old Models With the Transitional Scheme
What if you have an old model (saved prior to version 6.3) and it has slots displayed exactly as you like? Do you need to spend hours creating a scheme to match this? When a model saved in a previous version is first loaded, RiverWare will create a Transitional scheme that represents the user units defined in the model.
The transitional unit scheme has the following characteristics:
• It is complete, i.e., covers all unit types.
• It describes the existing slot configurations, that is, this scheme displays all slots as configured in the model file.
• It is compact, i.e., has the minimum number of unit scheme rules.
During model load, the unit manager loops over all of the slots and determines which set of display unit is most common for each unit type. That becomes the attributes for the Unit Type Rule. It then adds Unit Scheme Exceptions in increasing specificity until all slots are covered by the scheme. For equivalent units like “feet” vs “ft”, the most commonly used one is used throughout. Exceptions are not created for the other.
It is likely that many existing models will contain unintentional slot configurations which would show up as unique rules in the model transition scheme, typically with narrow applicability. For example, the most common unit might be 1.11 cfs, but then there are many instances of 1.123 cfs. Likely you just want the first one. To fix this, go into the Unit Scheme and remove the exception. Since the rules define exceptions to scheme, to get rid of the unusual cases, you need to delete the exception.
Changing Display Units on Slot Values
So you can make exceptions from the scheme, but you can also create them from the slot configuration. Yes, you can open a slot’s configuration dialog from the View, then Configure menu, you will get a dialog similar to Figure 3.5
Figure 3.5   
The dialog lists the unit type and the active scheme. You can then choose one of the following options:
• Use Flow settings.Use the Unit type rule.
• Use settings common to slots with the name “Inflow”. Use a previously configured unit name exception.
• Use custom settings below. Modify the units for just this slot. When you do this action, you are actually creating a Slot Exception for that slot within the currently active Unit Scheme. After making the change in the slot’s configuration, you can go to the unit scheme and see that exception.
As you change the selection, the unit settings for that toggle are shown in the Unit/Scale/Precision Format areas.
See “Configure Slot Dialog” for details about slot configuration.
Repairing Incorrect Units of Slot Values
Sometimes you enter values into a slot (by typing or importing) but then realize that the slot’s display units were not what you expected. For example, you want to enter 100cfs into a slot so you type it in. But, then notice the slot is showing the flows in cms, when you meant to enter them in cfs. So now the slot has a value of 100cms = 3531.5cfs. How do you fix this without re-entering the values?
To change the display units without changing the value displayed, you change the slot’s units from the slot using the View, then Configure menu. Configure that you wish to use custom settings, then change the units. Check the Repair incorrect units (within type only) box. When you apply the change and the confirmation dialog, the units will change, but the displayed values will not.
Note:  Technically, when the Repair box is checked, the underlying values do change. In the example above they change from 100cms = 3531.5cfs to 100cfs = 2.83cms. But, it appears that the displayed value stays the same.
Unit-specific Calculations
In general, RiverWare does calculations in internal units. Changing the scheme will not affect underlying results. But, there are a few methods that depend on one or more slot units. The methods are described, organized by the category of calculation.
For the methods in Table 3.3, a change in the units can produce different results due to calculations that use user-units in combination with a user-input exponent with units of NONE.
Table 3.3   
User Method
Link, in Objects
Groundwater Storage
Groundwater Outflow
Exponential Flow
Groundwater Storage
Deep Percolation
Exponential Percolation
Reach Evaporation
Inflow Exponent Pan Evaporation
Reach Seepage
Seepage and Riparian CU Loss
CRSS Sediment
Time Units
If the model timestep is 1 Month, the lag time slots for the methods in Table 3.4 must have TIME units of “month” or an error will occur.
Table 3.4   
User Method
Link, in Objects
Time Lag
Variable Time Lag
Drain Elevation
Stage Elevation Interpolation
Similarly, in one or more table slots for the methods in Table 3.5, the TIME unit must be “day” in the first column or an error will occur.
Table 3.5   
User Method
Link, in Objects
Gain Loss
Interpolated Flow Gain Loss
Variable Time Lag
Unit-dependent Calculations
The methods in Table 3.6 convert values to specific units for calculations. These calculations also use user-input parameter values with units of NONE. Changing the unit scheme should not change the results from these methods, but you must know the units used in order to set the parameter values appropriately.
Table 3.6   
User Method
Link, in Objects
Storage Routing
Variable Storage Routing
Depth to Flow
Power Function
Distribution Canal
Flow Routing
Storage Time
Distribution Canal
Flow Routing
Variable Storage Time
Sediment Transport
Perm Pool Sed (Pre2000)
Sediment Transport
Total Vol Sed (Post2000)
Unit Converter Dialog
The Unit Converter utility is a small calculator on the workspace which converts values using the same conversion factors used internally by RiverWare. To access the dialog, from the main workspace, select Units, then Unit Converter.
Converting Numeric Values
Figure 3.6 shows the Unit Converter dialog with all of the features displayed for numeric values.
Figure 3.6   
Following is the basic order in which the dialog is used and the options available.
1. Unit Type. Select the unit type for which the calculation should be done. Use the quick types buttons to select one of the four common types (Flow, Volume, Area, or Length) or use the pull-down menu to choose one of the less common types.
2. Value. Input a value to Convert From in the text box
3. Scale. Specify whether on not to use scale in either the from value or the result by toggling on the Include Scaled Units check box. When this box is checked, the Scale area is displayed. Then, enter a scale in the either of the two Scale text boxes.
4. Unit. Specify the user unit using the pull-down menu for both the from line and the result line. The unit menu contain all of the units of the selected type.
5. Duration for Rates. For units that include a rate (e.g. acre-feet/month) where the time scale is not constant (i.e. 1 Month or 1 Year), specify the duration. For monthly rates, select 28, 29, 30, or 31 days. For yearly rates, the specify 365 or 366 days.
6. Multiplier. Optionally enter a multiplier. The from value is converted to the units of the result and then multiplied by the Multiplier.
7. Result. The result is calculated immediately based on the specified input. The value which appears in the Result text field is now in terms of the new units, scale, and any specified multiplier.
8. Copy Result. You may wish to copy the result to the clipboard. Click the Copy Results button to copy the numerical value only. Hold down Shift and click Copy Result to copy the result and its scaled units.
The Unit Converter uses the conversion factors specified in the Units List dialog. To open the Units List dialog, from the Units menu in the main RiverWare workspace, select List Available Units. At the bottom left of the resulting Units List dialog, there is a check box to Show only units that are present on the workspace. Uncheck the box to show all available units and their conversion factors.
Converting DateTime Values to Numeric Values
Slots can store DateTime values; see “DateTime Values in Slots” for details. Internally, the dates are stored as numeric values. Sometimes, it is useful to convert the DateTime values shown to their encoded numbers. The Unit Converter provides one way to do this. Figure 3.7 shows the Unit Converter dialog with all the features displayed for DateTime values.
Figure 3.7   
When DateTime is the selected unit type, a different set of controls as shown.
Indicate the direction of the conversion by selecting one of the following options:
• DateTime to Numeric Value
• Numeric Value to DateTime
Following is the basic order in which the dialog is used and the options available.
1. In the DateTime to Numeric Value direction (shown in Figure 3.7), select the DateTime Unit (one of which is FullDateTime—fully specified absolute dates and times). The selected unit determines which controls are presented according to the relevant parts of a DateTime value. In the FullDateTime case, an additional checkbox switches between a conventional DateTime entry box to individual DateTime part controls.
2. When the Numeric Value to DateTime option is selected (shown in Figure 3.8), enter a numeric value (often you would copy/paste this as needed), and both the DateTime unit and value are displayed for that value.
Figure 3.8   
In both modes, the result is automatically computed as the inputs are modified. The result is selectable and copyable from the result field.
RiverWare supports the following units for the DateTime unit type:
• FullDateTime
• Month
• MonthAndDay
• TimeOfYear
• DayOfMonth
• TimeOfMonth
• TimeOfDay
• Year
Figure 3.9 shows units and controls.
Note:  DateTime values are stored in slots as floating point numbers. The integer part is the number of seconds since the beginning of 1800 (or, as RiverWare presents this, December 31, 1799, 24:00). For ordinary FullDateTimes, the fractional part is zero. Otherwise, the fractional part encodes which partial date time information is relevant. Year, Month, Day, Hour, Minutes, and Seconds.
Figure 3.9   
Revised: 06/03/2019