This document describes the following uses of units in RiverWare:

In RiverWare, all calculations are performed in standard or internal units. Table 3.1 lists the internal (standard) units for some common unit types.

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.

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.

A Unit Scheme describes how you want to display numeric slot values in terms of the following display attributes:

Figure 3.2 identifies the attributes.

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.

Figure 3.3 lists frequently asked questions (FAQs) and short answers, followed by links to more information.

Figure 3.3 identifies the main areas of the Unit Scheme Manager.

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.

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.

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.

The exported file is saved as an XML representation of the unit 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.

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.

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.

Following are examples of Slot Name Exceptions:

Following are examples of Slot Name Exceptions:

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.

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:

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.

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

The dialog lists the unit type and the active scheme. You can then choose one of the following options:

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.

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.

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.

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.

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.

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.

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.

Figure 3.6 shows the Unit Converter dialog with all of the features displayed for numeric values.

Following is the basic order in which the dialog is used and the options available.

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.

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.

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:

Following is the basic order in which the dialog is used and the options available.

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:

Figure 3.9 shows units and controls.