RiverWare 6.1: Unit Schemes / 8-10-2011
Unit Configurtion Data Inventory

1. Sources, Repositories and Uses of Unit Configuration Data in RiverWare
   1. RiverWare Unit Types Definition
   2. Standard RiverWare Units Definition
   3. "User" or "Display" Units
   4. Slot-Configured ("Local") Scale and Units
   5. "riverwareDB" file.
   6. Old-Style DMI control files and data files
   7. Database DMI "Dataset" Units
   8. Mapped Unit Schemes (new development)

[ See also Unit Schemes: Initial Release Options ].

(1) Sources, Repositories and Uses of Unit Configuration Data in RiverWare

(1.1) RiverWare Unit Types Definition

RiverWare defines a fixed set of unit types (currently 52 general purpose unit types), e.g. Flow or Volume. Those are hard-coded within the RiverWare implementation ...

• Units/UnitType.hpp ... typedef enum unit_type (e.g. FLOW)
• Units/StdUnits.cpp ... names of the unit types, and their Standard Units (see next subsection)

Unit types are associated with the following entities. The assignment of unit types to these entities is fixed, except in the case of entities which occur on Data Objects. (On Data Objects, the user assigns unit types to these entities using Slot Configuration editors) ...

• Single-column Slots.
  • SeriesSlots on Accounts have both "Primary" and "Alternate" Unit Types
• Multiple-column Slot Columns
• Optional Column Maps on Table Slots

Except for these entities on Data Objects, the associated unit types are defined in the Engineering Object, Account, Supply and Exchange class definitions of those slot-containing objects -- in Slot or SlotProxy C++ field initializers ... (Engineering Object Example ... Account Example).

A RiverWare unit type may also be dynamically associated with a numeric RPL value. (This doesn't really involve "configuration" data, except for the content of users' RPL code). RPL has its own unit system which is more general and dynamic than the RiverWare unit system; not all numeric values computed within RPL have a unit type represented within the RiverWare unit system.

(1.2) Standard RiverWare Units Definition

Hard coded into RiverWare (primarily in Units/StdUnits.cpp) is information about a "Standard Unit" associated with each RiverWare Unit Type. The primary unit-related information is a Standard RiverWare Unit name (e.g. "m3" for the standard "Volume" unit). There is also information:

• The number of seconds in per-time related Units, e.g. "cms" has a value one (1) because the denominator is "one second".
• The relationship to the standard unit used in Optimization. Technical note: the encoding of this information in Units/StdUnits.cpp is no longer used! The new (RPL-based) optimization encodes this relationship in RplUnitMgr::loadPreferredOptUnits().

(1.3) "User" or "Display" Units

The various units which can be chosen by the user for each of the RiverWare Unit Types are defined in the user-editable "units" file.

Primary fields for each Unit in the "units" file are:

• Unit Name
• Associated Unit Type
• Conversion factor with respect to the Standard RiverWare Unit for the particular Unit Type.

There is also support for summation (integration with respect to time) of units having a "per-time" factor into the integrated unit. The application of this information is very limited. This data provides a basis for implementing conversions between Flow and Volume (and Power and Energy) in time series without requiring the per-Slot "alt" unit configurations used in Account SeriesSlots AND without resorting to "magic" unit type knowledge in RiverWare.

(1.4) Slot-Configured ("Local") Scale and Units

The Slot-related entities having a Unit Type association (see section 1.1) can also be assigned a particular Display Scale and Display Unit. Those Slot-related entities are:

• Single-column Slots.
  • SeriesSlots on Accounts have both "Primary" and "Alternate" Units
• Multiple-column Slot Columns
• Optional Column Maps on Table Slots

Display scales are currently generally unrestriced floating point numbers, but are intended to be limited to non-negative powers of 10. (Currently, only the Periodic Slot configuration dialog and the Unit Scheme editor implements this restriction).

These assignments of Display Scale and Units to the entities above have been referred to as "Slot-Configured Units" or "Local Units" in recent Unit Scheme development documentation.

The Slot-Configured (or "Local") Scale and Units (and also Display Format and Precision) can receive values from the following SOURCES:

• "riverwareDB" file (see example) -- for only new Simulation Object Slots and unit-type configuration on Data Objects. (See next section).
• From loading a RiverWare model file, or importing a Simulation Object file.
• From copying or "cloning" an existing object (which is not actually supported in the user interface as a discrete operation).
• Edited by the user in any of the SEVEN configuration dialogs or "tabs":
  1. The main Slot Configuration Dialog (for Series and Table Slots: SlotConfigQtDlg).
  2. Periodic Slot Config Dialog (PeriodicSlotCfg),
  3. Scalar Slot Config Dialog (ScalarSlotCfgDlg),
  4. Multiple-Slot Configuration Dialog (aka "Configure Existing Slots" dialog, ConfigSlotsDlg),
  5. Accounting System Configuration Dialog (AccountingSysConfigDlg) ... This also sets units on the Prototype Accounts, so will also apply to newly created Accounts.
  6. Open Account Dialog, "Units" Tab (OpenAccountDlg).
  7. Exchange Configuration Dialog (ExchangeCfgDlg).

The following uses of these configuration values could potentially use instead a particular mapped Unit Scheme instance -- possibly the currently "active" mapped Unit Scheme.

• Scale and Units for Slot Value editing and display.
• Scale and Units for Output Device numeric output.
• Initial unit definition for the "unit fixup" function in Slot Configuration dialogs. (i.e. the UN-checked state of the "Convert" checkbox).
• Default Scale and Units for Old-style DMIs when the control file lacks a unit configuration for a particular Slot.
• Default Scale and Units for Database DMIs when neither the database nor the DMI's "Dataset" (its unit-type based unit map -- see below) provides a unit definition.

(1.5) "riverwareDB" file.

The user-editable "riverwareDB" file (see example) is a source of Slot-name, Slot column label, and Unit-Type indexed attributes, including Display Scale and Units. It has the following uses:

1. Initialization of slots' "local scheme" scale and units on new Simulation Objects, via the Prototype Objects (initialized only once at RiverWare startup).
2. Initialization of Data Objects' "local scheme" scale and unit configuration widgets when switching a Data Object slot entity to a new Unit Type.
3. Units and Scale for presentation of RPL numeric values outside of a "Slot context" (See option in RPL Parameters dialog).

(1.6) Old-Style DMI control files and data files

(1.7) Database DMI "Dataset" Units

A Database DMI "Dataset" in a RiverWare model can be used by multiple Database DMIs in that model. It allows the user to specify a Scale and Unit for each RiverWare Unit Type -- see image.

Within the Database DMI Dataset, the user can selected one of these three settings -- but not all three are applicable to the particular types of supported Database DMIs (e.g. Excel DMI Datasets don't support a "Database Units" source):

• Use Database Units
• Prefer Database Units
• Use Dataset Units

The unavailability of units for a particular slot may either generate an error OR may default to the slot's "local" (slot-configured) unit -- (sometimes? resulting in a warning) -- (I haven't yet looked at the specifics for the three different types of Database DMIs).

(1.8) Mapped Unit Schemes (new development)

A mapped unit scheme maps Unit Types -- optionally with respect to a Slot Name OR a Slot name on an Simulation Object or Account type -- TO numeric display attributes (Display Scale & Unit, Format and Precision).

We are envisioning the following types of mapped unit schemes:

• User Defined -- created by the user with a user-provided name; fully editable and deletable.
• Initialization Units -- non-deletable, but editable -- constrained to always be "complete" (see below).
• Predefined -- non-editable, possibly several instances (e.g. "U.S. Unit Scheme One").
• Standard RiverWare Units -- non-editable.
• [A "Unit Scheme" but not a "Mapped" Unit Scheme] ...
    Local Units -- represents the legacy "slot configured" display attribute settings.
   (We are considering removing this "legacy" units option).

A mapped Unit Scheme may be "complete" or "incomplete" with respect to Unit Types. As currently implemented, an "incomplete" Unit Scheme defaults to Standard RiverWare Units if no matching rule is found within the scheme for a given slot instance or unit type. (This can be changed to default to a well-known complete unit scheme).

One particular Unit Scheme will be the "Active" Unit Scheme at any given time. Uses of the "Active" scheme include:

• Scale and Units used in all slot data displays (notwithstanding a temporary override mode for individual slots).
• Scale and Units used by Output Devices in Interactive Mode (and maybe also in Batch Mode -- TBD).
• Scale and Units used in Open Slot Dialog "Import" and "Export" Operations, including "Export Copy" and "Import Paste".
• Scale and Units for presentation of RPL numeric values outside of a "Slot context" (for Batch Mode too? -- TBD) (See current option).
• Possibly: the initial reference scale and unit for Unit "Fixup" operations.

One or distinct stable unit schemes (possibly the "Initialization" scheme -- or something else) should probably be used for the following applications. Such Unit Schemes could be a "well known" and complete unit scheme (e.g. THE "Initialization" scheme), or unconstrained identification of a unit scheme selected by the user.

• Scale and Units for DMI operations when units are not available from the control file or database. This could somehow be integrated with the current function of the unit map within Database DMI "Datasets" ... compare with mapped Unit Scheme definition.
• Scale and Units for Output Devices in Batch Mode.

Note that IF the "Local Scheme" goes away as a selectable globally-applicable unit scheme (i.e. legacy slot configurations) ...

1. The "Initialization" Scheme should be renamed, e.g. to the "Default" Scheme, because the thing that it had been "initializing" has gone away.
2. The SEVEN related Slot Configuration Dialogs and Tabs virtually disappear or are greatly simplified (i.e. the non-display attribute configurations and unit type settings on Data Object Slots will still need to be supported).
3. We can canabalize the Slot class hierarchy display attribute fields which had implemented the "Local Scheme" -- FOR AN OVERRIDE MODE (i.e. to represent the override state). When initiating an override on a Slot, those fields would be initialized from the currently active scheme (for that Slot), and the user would modify only the display attributes needing to be overridden -- typically Display Precision -- but it could also be Scale, Unit or Display Format.

... See also: Unit Schemes: Initial Release Options.

--- (end) ---