RiverWare Scenario Enhancements / Scenario Playbox -- Design 3
Phil Weinstein / CADSWES / Edit: 1-3-2013 (1-4-2013, micro-edits).

Images for detailed design, in progress:

• [1-09-2013]  Playbox Screenshots (see also, for output section detail)
• [1-10-2013]  Playbox Configuration Screenshots (excerpt).
• [1-29-2013]  Scenario Mgr Baseline Tab and Snapshot Manager

Overview

This document proposes the following enhancements to RiverWare Scenarios.

• Automatic generation and maintenance of a set of special snapshot objects to represent scenario outputs.
• New "Scenario Playbox" dialog providing:
1. Slider-controlled adjustments to scenario input slots.
2. "Easy" plotting of scenario output slots based on dynamic list selections of scenarios and slots.

Prior Design Proposals:

• "Scenario Manager Dynamic GUI Enhancements Design for RiverWare 6.3" (July 2012)
  http://cadswes2.colorado.edu/~philw/2012/Scenarios/Design/
• "Design 2" / Scenario Playbox Mockup and Discussion Notes (Dec 2012)
  http://cadswes2.colorado.edu/~philw/2012/ScenarioPlaybox/Notes-Dec2012.html
  

Scenario Output / Snapshot Support

With RiverWare 6.2, the "Stakeholder's" (scenario user's) workflow generally consists of these steps:

1. Load a Baseline Model
2. In the Scenario Manager, create a new scenario. This contains new "scenario input slot" copies of a predetermined set of "baseline input slots".
3. Modify the values of the scenario input slots.
4. Run the model.
5. In the Snapshot Manager, "take" a new snapshot to capture the values of the output slots of interest which were generated from the scenario run. The first time this is done, the Snapshot Manager's "Slot List Template" needs to be set up to identify which slots from the model will be "copied off" to each new snapshot object.
6. Compare the output slots (series) of various scenarios and the baseline using RiverWare Plots or other analysis tools.

In Step 5, the user must manually operate the Snapshot Manager to capture the results of a scenario run. And it's up to the user to give the generated snapshot object a name which semantically associates it with the scenario.

We would like to automate this process with the following provisions:

1. The list of output slots to be captured as scenario results is maintained in parallel with the baseline model's scenario input slots. This is set up by the scenario engineer -- not the stakeholder. (The Scenario Manager will be enhanced to show, and support the editing of the output slot list). This slot list is used in place of the Snapshot Manager's slot list template.
2. A single snapshot object is generated for -- and associated with -- each scenario. This association is just "by name" -- the snapshot object's name is the name of the scenario. Renaming the snapshot object "breaks" the association.
3. At the end of a scenario run, the list of output slots are copied off to the scenario's snapshot object. If the scenario's snapshot object already exists, its output slots are overwritten by the new slots. Otherwise a new snapshot object (having the name of the scenario) is created.
4. Each scenario tab in the Scenario Manager dialog has a button to show the Open Object Dialog for the scenario's snapshot.

Note that while scenarios are saved in a "scenario" file distinct from the baseline RiverWare model, the scenario output snapshot objects are created within the model "proper" (not the scenario). Also note that the baseline model cannot be resaved -- it can only be "saved as" a distinct non-baseline model. The user may want to export the generated scenario output snapshot objects as distinct files, possibly in the directory containing the scenario file of the corresponding scenario.

Scenario Playbox (New)

The Scenario Playbox is a new dialog intended for stakeholders (scenario users). It facilitates a stakeholder's workflow of creating a new scenario, adjusting the values of up to three (3) predetermined scenario input slots with sliders, running the scenario, and comparing scenario output results.

In the initial implementation, only a single Scenario Playbox instance is provided. But this could be enhanced to support multiple named Scenario Playboxes associated with the baseline model.

Scenario Playbox Configuration

The Scenario Playbox configuration is created by the scenario engineer and is saved in the baseline model. This configuration is not editable by the stakeholder. It consists of the following properties:

1. A selection of up to three (3) scenario input slots to be adjustable by the user in the playbox. For each of these three slots:
   1. Whether the slot values are adjustable by scaling (multiplying by a factor) or by offsetting (increasing by a negative or positive amount).
   2. The "limits" of the adjustment values, corresponding to extreme ends of a slider control. The following method for specifying these limits is devised in order to have the slider's mid-point represent "no change". (Read more about the non-linear implementation of the scaling slider, below).
      • For scaling factor values, an upper limit (greater than 1.0) is specified; the lower limit will be the reciprocal of the upper limit.
      • For offset term values, a positive upper limit is specified; the lower limit will be the negative of the upper limit.
2. A selection of up to five (5) scenario output slots (from the new scenario output slot list).

These settings are made by the scenario engineer in a new "Scenario Playbox Configuration" dialog. This configuration dialog is shown by clicking the "Configure Playbox..." button on the "Baseline" tab.

Note that when a scenario input slot has been included in a playbox configuration, its values are no longer directly editable, e.g. in its Open Slot Dialog or an SCT. (It will be "read-only" in those dialogs). This is necessary because the values of such a scenario input slot are computed with a linear function of its corresponding baseline slot.

Accessing the Scenario Playbox

The Scenario Playbox is accessible from both the RiverWare Workspace and the Scenario Manager. If a Scenario Playbox has been configured, a "Scenario Playbox..." menu item appears in the Utilities menu, following "Scenario Management..." item. In the Scenario Manager, each Scenario Tab has a "Playbox..." button which brings up the playbox with the corresponding scenario initially selected.

Scenario Playbox Controls

The playbox has two major sections, described below:

• Top section: Scenario Input Adjustment Controls
• Bottom section: Scenario Output Plot Controls

This is in addition to the following general functions, made available as menu items (in the dialog's menubar), and in some cases, as icon toolbar buttons (basically the same set of toolbar buttons as in the Scenario Manager Dialog).

• Create a New Scenario (see below).
• Show the Run Control Dialog.
• Start a Run.
• Show the Scenario Manager Dialog.
• Show the Workspace.
• Show the Snapshot Manager.
• Show the Output Manager.

The "Create a New Scenario" function will create a new scenario with a new unique name in the form of "Unsaved Scenario#" (e.g. "Unsaved Scenario4") and will set the "Adjust Input Slots for Scenario" combo box (see following) to that new scenario.

Scenario Playbox: Input Adjustment Controls

Value adjustment sliders are presented for up to three (3) scenario input slots. Such slots from one particular scenario are effected, selected with this combo box:

Up to three panels -- for the each of the adjustable input slots -- are arranged horizontally. Each panel contains the following controls:

• Slot ID panel, including type icons and names of the containing object and the slot.
• A plot button to show a plot dialog with both the adjusted scenario slot values and its baseline slot values. If minimum and/or maximum limits are configured for the scenario slot, those limits are shown as horizontal markers in the plot.
• A slider panel -- of either the "scale" or "offset" type -- SEE IMAGE BELOW. Each includes:
  • An editable numeric field showing the value of the current slider position. The entry field is also directly editable.
  • A horizontal slider control.
  • Three numerically labeled buttons -- see description below.
  • For the "offset" type only: a unit indication.

The Scale slider bar is exponential. The range is based on the upper value set by the scenario engineer. The lower limit of the range is the reciprocal of the specified upper value. The mid-point is always "1", which results in no difference from the baseline slot values. Note: although the scale slider bar’s positions are interpreted logarithmically, the slider’s tick marks are evenly spaced; this is a limitation of the Qt4 slider widget.

Detail: Numeric computations for the "exponential" scale slider bar are defined on this webpage:
     Scale Slider Formulas
     http://cadswes2.colorado.edu/~philw/2012/Scenarios/Design/SliderScrollFormula.html

The Offset slider bar is linear, and ranges from the negative value to the positive value of the adjustment limit value set by the scenario engineer. The mid-point is always "0", which results in no difference from the baseline slot values. The Offset values are in the display units for the slot. Note that offsets are applied in user-units -- so, in the case of "irregular time" units such as "acre-feet per month", the adjustment to the underlying standard values (e.g. "cms") is different depending on the month or year in which the timestep occurs.

When a slider bar has "focus" (e.g. after it has been clicked), the slider "thumb" can be stepped by a small amount by pressing the right or left arrow keys (i.e. on the keyboard). Holding down those arrow keys for about one second causes them to repeat, effectively animating the motion of the slider thumb and resulting value.

The three numerically labeled buttons below the slider function both as a slider "value key" and controls to set the slider to the corresponding positions. The middle position represents the "null transform" for each of these functions, 1.0 and 0.0 respectively for "scale" and "offset".

The actual computation of the scenario input slots from the baseline slots -- as a linear function using the scale or offset values -- occurs generally after the slider has stopped moving (for about half a second). Any plots or Open Slot Dialog showing the scenario input slot's values will immediately show the new computed values.

The computed scenario slot values are "clipped" at the configured minimum and maximum values for the baseline slot -- if those have been configured. This is not considered an "error condition". (Note that these minimum and maximum values should not be confused with the adjustment limit values which apply to the coefficients of the linear adjustment transform function. These minimum and maximum values are applied to the results of that function).

Scenario Playbox: Output Plot Controls

The bottom section of the Scenario Playbox is for showing scenario results (outputs), in the form of a plot. It consists of three components:

• A list of the defined scenarios -- supporting multiple ("extended") item selection.
• A list of the Playbox's scenario output slots -- supporting single item selection.
• A "slot plot" (similar to that shown in the Plot Dialog), including the curve legend below the plot.

The slot plot is updated as the selections in the two lists are changed. A curve is shown for each of the selected scenarios' copies of the single selected output scenario slot. A curve for the baseline slot is always shown.

Impact on Snapshot Manager

We have now introduced a new type of snapshot object -- whose list of slot copies is different from the Snapshot Manager's slot list template. This isn't really a problem, as the list of slots in each of the snapshot objects is no longer dynamically "synchronized" with that slot list template. Scenario output snapshot objects will appear in the snapshot object list (bottom-right panel) having the names of scenarios which had been run. The user is free to delete scenario output snapshot objects -- they will be recreated the next time the scenario is run.

Persistence Issues

All new persistent information resides in the RiverWare model file. (Nothing is being added to scenario files). This new information consists of:

• A single scenario playbox configuration record. This will have a hard-coded name to be upward compatible with a possible future enhancement of supporting multiple named scenario playboxes.
• The scenario output slot list.

--- (end) ---