GUS (Grand Unified Selector) Test Guide
for RiverWare Release 4.6 (April/May 2005)

Edit: 4-22-2005, Phil Weinstein
See also accompanying screenshots.

The upcoming RiverWare release will include the initial implementation of the "Grand Unified Selector" as a replacement for the old Multiple Object and Multiple Slot Selectors. This shows up in about ten different places within RiverWare. GUS does not yet support selection of Account Slots (or any Accounting Slots). This was also a limitation of the old Multiple Slot Selector. So, many "client" dialog boxes used to have, and still do have, two separate buttons or menu items for (physical) "Slots" and "Account Slots". GUS is now shown for only physical Slot selections.

A description of the GUI features of the GUS Selector are intentionally omitted from this document. It is important to know if the user interface features are sufficiently self-explanatory after a little experimentation on the part of the user.

Showing the old Selectors

Those old selectors can be shown (instead of the new GUS selectors) by defining the following environment variable:

setenv RW_GUS_PORT_DISABLE 1

In a few cases, GUS allows the selection of a broader set of Slots than did the old Multiple Slot selector.

In code, individual uses of the new GUS Slot Selector can optionally enable the new capability of allowing the user to view and select AggSeries Slot Columns and/or Table Slot Columns and/or TableSeries Slot Columns. If any "slot column selection" capabilities are enabled, there are toggle buttons at the top of the Slot selection panel to show or hide slot columns, which are displayed as "tree-view" child elements under their containing AggSeries or Table Slots. [Figure 4 shows TableSeries "Columns" under the "Reservoir Summary" Table Series Slot].

It will be important to determine whether clients for which we have enabled AggSeries Slot Column and/or Table Slot Column selection behave correctly when those types of items are selected. In most instances of Slot Selection, AggSeries Slot Column selection IS enabled, since AggSeries Slot Columns are, in fact, plain Series Slots. However, Table Slot Column selection is enabled only for the SCT's use of the GUS Slot Selector, since Table Slot Columns (including TableSeries Slot Columns) are not actual Slots -- so special provisions of the client dialog box would be necessary to support those.

Some Testing Criteria

1. Usability: Are the types of selections which the user would want to perform from the various "client" dialog boxes easy to do? Does it take an excessive number of mouse clicks and drags to perform simple selections? Are windows popping up in inconvenient places?
    
2. Do the selections work within the Client dialog box? Where AggSeries and Table Slot Columns are selectable, are they treated correctly within the client? (e.g. shown with a name which indicates both the parent Slot and the column label or index?). If unusual slot types are selectable (Scalar Slots, ListSlots, PeriodicSlots), are they treated reasonably within the client?
    
3. Do selections made with GUS "round trip" correctly to the model file, or other file in which the client dialog box saves its selections?
    
4. Does RiverWare ever crash, e.g. by deleting objects after they have been included in a Selection? Note that Slots on Data Objects can be added and deleted by the user.

The GUS Selector Clients -- Overview
See also detailed sections, below.

[All/No] -- Optional "All (objects)" and "No (objects)" buttons are used to select special states.
[Auto-Apply] -- Selecting an item causes an update in the client dialog box.

(1) Multiple Object Method Selector

Workspace menu >> Workspace >> Objects >> Select Methods on Objects ...

The "Add Object(s) ..." button brings up the GUS Object Selector in multiple-selection mode. Data Objects and SnapShot objects are excluded. Selected Objects are added to a list of SimObjs in the Multiple Object Method Selector.

(2) Diagnostic Settings: Simulation Diagnostics
(3) Diagnostic Settings: Rulebased Simulation Diagnostics
(4) Diagnostic Settings: Accounting Simulation Diagnostics
(5) Diagnostic Settings: Optimization Diagnostics
(6) Diagnostic Settings: Workspace Diagnostics

Workspace menu >> Utilities >> Diagnostics Manager...

There are two columns of pushbuttons corresponding, roughly, to the different modeling controllers. The "Accounting..." button is enabled only if Accounting is enabled in RiverWare [Workspace menu >> Accounting >> Enable Accounting].

Each of the five "Edit Diagnostic Settings" dialog boxes are divided into panels corresponding to the diagnostic filtering domains supported for the controller (e.g. Objects, Accounts, Slots, Rules). For each of those domains, a set of instances for which diagnostics are to be generated can be defined. The user can also choose "All (objects)" or "No (objects)" for any of the diagnostic filtering domains. [See the two extra buttons above the "OK / Apply / Cancel" buttons in Figures 5 through 7].

Making a selection of items in GUS adds the selected items to the list within the Edit Diagnostic Settings dialog box. Redundantly added items are ignored. Pressing "All (objects)" or "No (objects)" within GUS replaces the entire list with an indication of the corresponding special state, and dismisses GUS.

(7) Output Configuration Manager

Workspace menu >> Utilities >> Output Management >>
... (in the Output Manager dialog): "New ..." button.
... (in the resulting Output Configuration dialog): "Select Slots..."

Notice that, in the Output Configuration dialog (where the topmost widgets will initially say: Output Type: Plot Page), there are actually FOUR applications of this dialog box for different kinds of output. These are selected in the topmost option menu with the following four options. Each of these should be tested.

• Plot Page
• Xmgr Data Format File
• RiverWare Data Format File
• Comma-Delimited Format File

All types of Table Slots (including Table Series Slots and Periodic Slots) are excluded. AggSeries Slot Columns are enabled for selection.

Making a selection of Slots in GUS adds the selected Slots to the list within the Output Configuration dialog box. Adding Slots which are already in that list has no effect.

(8) Snapshot Manager

Workspace toolbar >> (Camera Icon) ...

Press the "Add Slots..." button to bring up the GUS Slot Selector. Snapshot Objects are excluded. (You can't take a Snapshot of a Snapshot). AggSeries Slot Columns are enabled for selection.

Making a selection of Slots in GUS adds the selected Slots to the list within the Output Configuration dialog box. Adding Slots which are already in that list has no effect.

(9) Edit (User-Defined) SubBasins

Workspace menu >> Edit SubBasins ...
(from the Edit SubBasins menu bar) ... View >> User-Defined Subbasins
(from the Edit SubBasins menu bar) ... Subbasin >> Append New (or Typed) SubBasin
... select the new SubBasin row.
(from the Edit SubBasins menu bar) ... Invoke Member Selector

The GUS object selector is shown. CompObjs and SnapShotObjs are excluded. Making a selection of SimObjs in GUS adds the selected SimObjs to the TreeView child items under the selected User-Defined SubBasin. Adding SimObjs which are already included in the selected User-Defined SubBasin brings up a "Confirmation" dialog box with this message:

"The following objects are already members of the subbasin:" ...
(followed by the names of the redundant objects in a ListView).
[OK] [Cancel] -- note: these do the same thing: dismiss the confirmation box.

(10) Supplies Manager

Workspace menu >> Accounting >> make sure "Enable Accounting" is checked.
Workspace menu >> Accounting >> Supplies Manager ...
(from the Supplies Manager menu bar) ... Object >> Select ...

The GUS object selector is shown in single-selection mode. SimObj Types which do not support Accounts are omitted. (But SimObjs which lack actual Accounts are still shown -- unless the "Has Account" filter in the GUS SimObj panel is used to exclude those SimObjs). Through the use of GUS' "auto apply" feature, selecting a SimObj in GUS immediately sets the "reference object" in the Supplies Manager.

(11) Reservoir Selector
e.g. for a ListSlot on a Control Point object.

From the Workspace, open (double-click) (or create and open) a Control Point object. Then open (double-click) the Upstream Reservoirs Slot, which is a ListSlot. (Any ListSlot on a Control Point object will do). In the ListSlot editor dialog box, click the leftmost toolbar button, which is for Appending a Slot.

The GUS object selector is shown in single-selection mode, for Reservoirs only. Using single selection mode is a little strange -- it forces the user to select Reservoirs in a particular order. This may not be necessary because the ListSlot editor has very convenient controls to move items up or down in the list.

The ListSlot shows an error dialog box ("RiverWare Error: Cannot add the row") if the user dares to select a Reservoir which is already in its list. This condition should perhaps be just ignored (NOP) instead of being reported to the user. Or, perhaps GUS (and the RootSelection class) should support the ability for the client dialog to provide a list of items which should be excluded (either hidden or disabled) from the selection. Note, however, that the use of ListSlots in RiverWare is still very rare, AND, I believe, the ones that are used (on Control Points) are unlikely to be changed once the model is set up -- so improving this particular editing scheme is perhaps not too important.

(12) SCT

Either open an existing SCT (using the Workspace's SCT toolbar icon -- the grid icon) or create a new SCT:
Workspace menu >> SCT >> New SCT ...
(in the case of a New SCT, you can just click "Add Slots" on the popup dialog box), or
Make sure the SCT is unlocked. (See the Lock icon on the left side of the toolbar).
SCT menu >> Slots >> Append >> New Slots ...

The GUS Slot Selector is shown in multiple-selection mode. Only "Series-like" Slots are displayed -- both actual Series Slots (including AggSeries Slots, MultiSlots, Expression Slots, etc.) and TableSeries Slots (which are, in fact, Table Slots, but they, and their individual columns, are technically not Series Slots). Both AggSeries Slot Column selection and TableSeries Slot Column selection are available. [See Figure 4].

Selected Slots are added to the SCT, without any restrictions of uniqueness. That is, a given Slot can appear in an SCT more than once.

(13) Scenario Manager

Workspace menu >> Utilities >> Scenario Management ...
(from the Scenario Manager menu bar) ... Configuration >> Add Slots ...

The GUS Slot Selector is shown. Slots are limited to the following types:

• Series Slots (all types, including AggSeries, MultiSlots, Expression Slots)
• Table Slots (all types, including TableSeries and Periodic Slots)
• Scalar Slots

AggSeries Column selection is available. [IS THIS OK?]

Selected Slots are added to the Baseline slot set. Redundant Slot selections (i.e. selecting Slots which are already in the Baseline slot set) are ignored.

(14) MRM Slot Store
Multiple Run Management

Note: Bill is re-implementing the MRM dialog boxes in Qt, including the required GUS integration for physical slot selection. As of right now, this is not in the build. And when it is, it may look a little different than what I'm describing here.

Workspace toolbar >> Two running people icon
... this brings up the Run Control dialog (in the more complex MRM configuration).
(from the Run Control menu bar) ... View >> Output Slot Lists ...
... this brings up the MRM Slot Store dialog box.
(from the MRM Slot Store menu bar) ... Edit >> Select Slots ...

As of right now, this brings up the "MRM Slot Selector" (which was the original Multiple Slot Selector). But it should bring up the GUS slot selector -- with one difference: In place of the "Ok / Apply / Cancel" buttons are "Add / Delete / Close" buttons.

[Note (4-21-2005, Phil). I'm realizing now that some more GUS work may be needed to support this. I did implement a provision for changing the button labels, but the first button shouldn't dismiss the dialog when that button is used for the MRM Slot Store "Add" operation].

Note that the MRM Slot Store has a "File >> Save As ..." function which saves the list of selected slot names out to a file. This feature is important to users who need to create such files. See, for example, this use case description ... Use Case of old Multiple Slot Intersection Selection (3-2-2005, 3-pages).

--- (end) ---