RiverWare 6.1: Unit Schemes
Unit Schemes: 7-25-2011 Status Report
Edit: 7-25-2011, Phil Weinstein, CADSWES

• Work on Unit Schemes completed since last software meeting
• Major areas of remaining work
• Action Items

• Set Environment Variable: setenv RIVERWARE_SHOW_TEST_MENU 1
• Select "Test 3" from the RiverWare Workspace "Test" Menu
• Note: The checked-in code doesn't support actual Unit Scheme "Effects".

Work on Unit Schemes completed since last software meeting

... from Tuesday 7-19-2011 to Monday 7-25-2011:

RECENTLY COMPLETED FUNCTIONALITY:

1. Unit Scheme "EFFECTS" are working -- needs more review and testing. (This is implemented only in Phil's builds; not checked in). The fundamental changes were to the representations of display attribute configuration values within the SeriesSlot, TableSlot and ScalarSlot classes from discrete fields to NumDisplayAttribs instances, and having general references to those entities use the new Unit Scheme switching mechanism implemented in the base Slot class -- except for references having to do with configuration of those entities (which applies specifically to the "local" NumDisplayAttribs instances).
2. De-"effectizing": SlotConfigQtDlg (the main Slot config dialog) -- but needs more testing. Certain slot display attribute "clients" need to specifically use "local" display attributes instead of the unit scheme "switched" attributes. (Much of the remaining development work is of this type).
3. XML serialization of Unit Schemes using QtXml DOM classes.
4. Export and Import of Unit Schemes to individual XML-encoded files. Import allows either adding rules to current scheme, OR replacing the current scheme rules. The implementation includes substantially comprensive error reporting.
5. Persistence of mutable Unit Schemes in the RiverWare model file.
   • Note: Saving Unit Schemes in model files is currently disabled in the checked-in code. See the "DUMP_UNIT_SCHEMES" constant in SimWS.cpp.

RECENTLY COMPLETED SOFTWARE ARCHITECTURE IMPLEMENTATIONS:

1. Moved MappedUnitScheme data classes to UnitScheme inner classes.
2. Moved computed prioritized rules from UnitSchemeMgr to UnitScheme, for direct use of UnitScheme to provide NumDisplayAttribs values, in preparation for initialization algorithms and replacement of other clients of the current riverwareDB resource database.
3. Layered reimplementation of internal UnitScheme initialization ... and "production" implementation of predefined schemes.
4. Changed Slot Unit Scheme Attribute Cache from QList to QVector.
5. Initial support for single-character Display Format codes, to support gradual migration from the two-character QString encoding. (The NumDisplayAttribs class uses single-character format codes, though it has methods to also support the two-character codes).

Major areas of remaining work:

(1) Unit Scheme De-"effectizing"

The "clients" of Slot display attributes which should not use the Unit Scheme "switched" variant of those entities need to be recoded to make explicit use of the "local" attributes residing on Slots (effectively, the "legacy" configurations). This applies to:

1. Configuration dialogs. The main Slot Configuration Dialog (for Series and Table Slots: SlotConfigQtDlg) is basically done -- needs more testing. Similar configuration dialogs needing this treatment are:
   1. Periodic Slot Config Dialog (PeriodicSlotCfg),
   2. Scalar Slot Config Dialog (ScalarSlotCfgDlg)
   3. Multiple-Slot Configuration Dialog (aka "Configure Existing Slots" dialog, ConfigSlotsDlg),
   4. Accounting System Configuration Dialog (AccountingSysConfigDlg)
2. Certain default cases in DMI, including old-style DMIs where the control files don't specify units, and Excel database DMIs.
   • Related Task: Old style DMIs will issue a single warning indicating the number of slots for which no units were available from the control file. Also, an optional diagnostic message for each such slot.
3. Open Slot Dialog's "Local Slot Units Override" Display Mode (forcing the Local Scheme just in the dialog). This requirement involves not only accessing local display attributes, but also rewriting the "display string" preparation methods to conditionally use those attributes.
   • Note: Beyond proposing a GUI design for this feature, for review, I suggest that it be left to the last, and be implemented after internal acceptance of the Unit Scheme "effect" code (with checkin to 6.1 development). This feature represents a "break" from the Unit Scheme architecture which should be confirmed as working before we attempt to implement a deviation from that architecture.

(2) Removal of the Resource Database ("riverwareDB" file); Use of the "Initialization Unit Scheme" for Slot initialization and default display attributes.

The "Initialization Unit Scheme" instance (of the UnitScheme class) is ready for replacement of display attribute-related references to the Resource Database. Resource Database entities not supported by Unit Schemes (i.e. min/max values: None; convergence type and limit) will supported by hard-coded defaults; users will have to configure those in the Multiple Slot Configuration and Accounting System Configuration dialogs.

However, if we decide to implement a migration capability from the Resource Database to the Initialization Unit Scheme, instead of removing the Resource Database code, will will have to retain much of it, but just limit the use of its API. This should, at least, be a first step in moving the Resource Database clients to the Initialization Unit Scheme.

Other TO DO:

• Enforcement of the Initialization Scheme having display attribute configurations ("rules") for all of the Unit Types has not yet been implemented. It is possible to remove those rules. That needs to be prevented.
• On program startup, inform the user that a "riverwareDB" file has been found but is no longer being used.

(3) Numeric Dimension Display Attribute Support

This was overlooked in the original design. In addition to the array of NumDisplayAttribs which TableSlots maintain for each of their columns, a single NumDisplayAttribs instance needs to be supported for the Numeric Dimension. This will be parallel to the existing support in the Slot and TableSlot classes. Until this is implemented, Numeric Dimensions (Numeric Column Headers) will effectively be "stuck" on the "Local Scheme".

(4) Remaining GUI Development

• Deploy the Unit Scheme selection menu within a new Workspace "Units" menu. See the "Unit Scheme GUI Controls" section on this webpage ... 7-28 update.
• The Slot Configuration Dialogs need to be "framed" as pertaining to the "Local Slot Units", to clarify that they are distinct from units configured via Unit Schemes. (We are unsure about exactly what words to use).
• Design of GUI controls for "Local Slot Units Override" mode in the Open Slot dialogs and their associated Slot Configuration dialogs. In both types of dialogs, it should be possible to place the Open Slot Dialog in this mode. The Open Slot dialogs will need a clear indication that they are in this mode AND a readily available control to cancel the mode. This will initially be demonstrated in the main Open Slot Dialog and its Slot Configuration Dialog, and then will need to be applied to also the Periodic Slot and Scalar Slot dialogs, and their configuration dialogs.

(5) Architectural Tasks

• Optional: Complete removal of two-character (QString-encoded) Display Format codes.

Action Items

(1) Development Priorities (Next Steps)

• Complete basic features of Configuration Dialogs: (a) Unit Scheme De-"effectizing" (i.e. proper operation), and (b) Adding "Local Slot Units" descriptive language.
• GUI Design of controls to support the Open Slot Dialog's "Local Slot Units Override" mode.
• Workspace "Units" menu. (See the "Unit Scheme GUI Controls" section on this webpage).
• Recoding uses of Resource Database display attributes to using the Initialization Scheme.

(2) Review of Slot Class Hierarchy changes to support Unit Scheme "Effects"

Unit Scheme "Effects" seem to be working (i.e. in my own development area). Some testing and debugging has already been done.

In the modified Slot classes (in my development areas), the legacy display attribute data members have been REMOVED, and the new NumDisplayAttrib data members represent the actual "local" values. These changes have been coded and seem to be working for all three relevant Slot subclasses where display attributes live: SeriesSlot, TableSlot, and ScalarSlot. (See also the first item in the "Recently Completed" section at the top of this document).

The type of issue I'm concerned about is particular uses of display attributes explicitly using local attributes when, and only when necessary. I'd expect problems to show up only when a Unit Scheme other than the "Local" Unit Scheme is active.

See the changes in this Solaris development area (SIM library). Most architectural changes are in the SeriesSlot, TableSlot and ScalarSlot classes.

• /projects/riverware/staff/philw/Four/Sim/

The implementation should be reviewed and tested AFTER the basic operation of the Configuration Dialogs has been finished (the next development step). It would be good to get this checked in (at least into a CVS branch, if necessary) before attempting architectural deviations, such as the implementation of a "Local Slot Units Override" mode.

(3) Minor Action Items:

• Acquisition of important examples of "production" riverwareDB files from major modeling projects.
• Decide on names for, and definitions of Built-In (predefined) Unit Schemes. The development code has an arbitrary "U.S. Unit Scheme One" unit scheme, which has been useful in testing, but which won't be released in its current form.
• Decide how to refer to "Local Slot Units" / the "Local Slot Unit Scheme"?

--- (end) ---