Design Document / Author: Phil Weinstein, David Neumann, Edie Zagona / CADSWES
|
The Mass Balance Summary is a user-defined hierarchy of series slot collections used to check mass balance across many objects in a RiverWare model. Any data object can optionally have a Mass Balance Summary definition. Series slots representing sums of the sets of series slots are maintained on the data object, and can be referred to from Rpl expression slots defined by the user for any summation calculations not provided by the Mass Balance Summary, e.g. annualization of sums.
The Mass Balance Summary design was derived from a Rpl expression slot-based implementation by the URGWOM team (Upper Rio Grande Water Operations Model) -- a version of the "MRGV 2011 calibration" RiverWare model. This particular mass balance calculation involved 162 Rpl expression slots to sum 560 physical series slots. Data from this URGWOM model was used to demonstrate this GUI design.
A Mass Balance Summary ("Summary") can be associated with any data object. The configuration of the Summary is saved with the data object in RiverWare models and in data object (simulation object) export / import files.
Primary Configuration Data:
 |
Four level-hierarchy of Series Slot references. Each collection item represents the series sum of its child items' series.
| Collection Level | Generated Summation Slot Type |
Background Color |
|
| 1 | Water Balance Groups | Series Slots | Pink |
| 2 | Water Balances | Agg Series Slots | Cyan |
| 3 | Slot Groups (+/-)* | ... child Series Slots | Yellow |
| 4 | Slots | Series Slot References | Green |
*Each Slot Group will be summed as a Credit ("+") or Debit ("-") for its containing Water Balance. (Note: the Credit and Debit annotations shown in the mockup images in this document are arbitrary. They are not derived from the reference model).
The set of generated series slots (and aggregate series slots) used to represent sums in the top-three levels is automatically maintained. The values of these slots will be computed internally in C++ implementation rather than with Rpl expression slots. The generated slots are "read-only" -- their values will not be editable by the user.
The lowest level -- references to series slots in the model -- can include references to user-defined Rpl expression slots to compute terms which are not directly available as RiverWare slots at the same timestep. The reimplementation of the URGWOM mass balance calculation using the new Mass Balance Summaries will need:
Other Configuration Data:
Each computed summation series slot -- for the items in the top three levels -- is the sum of all the contained items' series slots at each timestep -- with debit (negated) terms supported at the Slot Group level. The time range of a computed slot is the extrema of time ranges of the contained items.
When Summaries are computed will depend on the performance of the calculations (TBD). (We'll finalize this decision during development). The following events will result in either performing the computation OR visually marking the Summary display as "dirty" (needing a recomputation):
Before a Summary recomputation, any "missing" computed summation series slots are created on the data object, and "orphaned" series slots -- i.e. previously created summation series slots which are no longer used, e.g. as a result of an item name change -- are destroyed. These series slot maintenance adjustments will be performed also as a result of certain edits to the Summary configuration.
After each Summary recomputation, the "dependent" Rpl expression slots in a special user-configured ordered list are evaluated. Read more in the Mass Balance Summary Configuration section, below.
 |
A Mass Balance Summary can be created on any data object with the "Add Mass Balance Summary..." operation in the Open Data Object dialog's "Edit" menu. This shows the Mass Balance Summary dialog in its configuration mode.
A data object having a Mass Balance Summary is indicated in the object type description (see below). When a Summary exists, a "Mass Balance Summary..." item appears in the Open Object Dialog's View menu. (And the "Add ..." item in the Edit menu is changed to "Mass Balance Summary..." as well).
Possible Enhancements:
 |
Already existing Summaries are accessible from the Workspace menu in the
RiverWare Workspace.
 |
The Mass Balance Summary dialog is accessible from the Workspace menu and from the Open Data Object dialog (as described above).
Clicking the data object icon button at the top of the dialog shows the Open Object Dialog for the data object containing the Mass Balance Summary.
The four supported levels of summation sets are represented with color-coded buttons -- clicking these buttons opens up the tree view to the particular level.
Subtrees can also be opened and closed in the normal way, with the tree controls.
The integer shown to the left of the level buttons indicates the number of defined items at that level. For example, the screenshot shows that this Summary contains 6 Water Balance Groups, 19 Water Balances, 137 Slot Groups, and 560 Slot references.
Each line in the tree view represents a computed summation series slot or a referenced series slot (in the case of the fourth level). Context menu operations on the set of selected lines include:
Possible Enhancements:
 |
Data columns show numeric values in the selected flow or volume slots, with display units selected in this dialog. The illustrated volume and flow units (to the right) are supported -- as defined in the currently available standard RiverWare "units" file.
The following data columns are supported:
*conditionally hidden or shown, based on a configuration setting.
Numeric summation data is shown only for the item levels with a checked "values" checkbox to the right of each level button -- see below. This allows the user to quickly scan through similarly "scoped" sums (e.g. only Slot Group sums).
Possible Enhancement: Add buttons along the bottom of the Mass Balance Summary dialog, mostly for operations which apply the the selected set of items.
Above: Water Balance Groups (level 1). Right: Slot Groups (levels 1, 2 and 3).
|
 |
 |
The Mass Balance Summary Dialog supports "File" and "View" menus.
TBD: The "Export" and "Import" operations will be used at least for development testing of the Summary configuration serialization. We might not choose to support this in the final implementation. Note that a data object's Mass Balance Summary configuration will be included in the SimObj "export" file for the data object.
The "Delete Mass Balance Summary" operation removes this Mass Balance Summary from its data object, after a confirmation by the user.
Two types of columns will optionally be shown in the tree view, based on checkboxes in the "View" menu:
The "Adjust Columns" operation adjusts the width of each column to the content of that column.
The tree view context menu ("right-click" menu) operates on the full set of selected items:
When the Mass Balance Summary dialog's "Configure" group box toggle is checked, the following occurs:
 |
The "Edit Operations" Configuration Tab provides context-sensitive edit controls for the first three item levels. (The enabledness of each item depends on the tree view item selection). Some of these operations are also available in the context menu.
Additionally, there are the following buttons for Slot Groups:
 |
The "Slot Generation" Configuration Tab provides settings for names given to the automatically generated summation slots -- for items in the top-three levels. These settings are intended to address these two issues:
By default (as illustrated), a prefix of "mb_" is used for generated slot names. The user has the option of omitting that prefix or specifying a different one -- individually for Water Balance Groups (level 1) and Water Balances (level 2). Note that the generated slots for Slot Groups (level 3) will be child "columns" of the Water Balance aggregate series slots -- no prefix will be prepend to the column labels for those series slots.
The tree view's "Abbreviation Column" is conditionally shown, based on a checkbox in the View menu. Clicking the "Show Abbreviation Column..." button turns that checkbox on and shows the column. Text in the abbreviation column is directly editable (inline) only when the "Configure" group box is open (checked on).
 |
The "Dependent Expression Slot" Configuration Tab provides a user-defined ordered list of Rpl expression slots to be automatically evaluated at the conclusion of the Summary recomputation.
The example to the right enumerates annualization Rpl expression slots in the URGWOM reference model. (Their Rpl expressions will be recoded to refer to generated Summary summation slots).
An added benefit of the enumeration of slots dependent on the Summary summation slots is to explicitly represent the purpose of those slots -- i.e. being part of a mass balance computation.
The arrow icon buttons move the set of selected items up or down in the list.
The "Add..." button brings up the slot selector to pick slots to be added to the list. The selector will be initialized to show only series and scalar slots having Rpl expressions.
The "Remove" button will remove the selected items from the list, after a confirmation by the user.
A context menu on this list will provide the following operations -- similar to those in the main tree view context menu:
Note, however, that these slots can effectively be added only to SCTs showing series with the same timestep size.
The Mass Balance Slot Group Configuration dialog is shown modally when clicking the (Slot Group) "Configure..." button in the Mass Balance Summary Dialog. This configuration dialog is used to define the set of Slot references in each of the Slot Groups within a Mass Balance.
This dialog presents lists in four quadrants:
Slots can be moved between the bottom two quadrants (Slot Group Slots and Available Slots) with the large arrow buttons between those two quadrants.
If no un-applied changes have been made to the Object Filter list (not including item selections) or the Slot Group Slots list, the OK and Apply buttons are disabled, and the "Cancel" button is instead labeled "Close".
The "OK" button applies the not-yet-applied changes to the Mass Balance Summary configuration and dismisses the dialog.
The "Apply" button applies the not-yet-applied changes to the Mass Balance Summary configuration, but does not dismiss the dialog.
The "Cancel" / "Close" button dismisses the dialog without applying new changes to the Mass Balance Summary configuration.
When applying changes, if any of the Water Balance's Slot Groups contain slots not on the simulation objects in the Object Filter, a warning is shown, giving the user the option to (1) automatically add the missing objects to the Water Balance's Object Filter -- OR (2) ignore the condition OR (3) cancel the "apply" or "OK" operation.
The generated Summary summation slots will be viewable in the SCT and Open SeriesSlot Dialogs in the usual way. When using the special "show in SCT" operations from the Mass Balance Summary dialog, divider items with text will be generated for the names of the containing higher-level objects.
TBD: We'll need to decide how the SCT Slot Item labels are set -- i.e. whether they the primary names of the various items OR the names of the generated slots (which use the configured abbreviations, when available). This might be done differently for the two axis orientations, and we might decide to add user-settable preferences for how SCT Slot Item labels should be composed.
Possible Enhancement: Credit / Debit Slot Annotation ...
We could consider adding flags to Series Slots to indicate that the slot represents a "Credit" or "Debit", and enhance the Series Slot Displays (SCT and Open SeriesSlot Dialog) to show a plus ("+") or minus ("-") with the slot label in the row or column header, something like this ...
|
It will be important for the Mass Balance Summary mechanism to recognize slots which had been created for summary series. Such slots no longer corresponding to series items in the configuration (related by user-defined names and abbreviations for those items) need to be removed. An easy way to accomplish this is to add a "Mass Balance Sum Slot" Slot Attribute bit.
Similarly flags could be added to support a Credit / Debit Slot Annotation (see prior section). Fundamentally, this needs three states which could be represented with two attribute bits (in a couple distinct possible ways, TBD).
A "change in storage" entity was required for the URGWOM mass balance computation. This was done using Rpl expression slots (6 of them), and still could be. But we could consider adding a FLOW slot on reservoirs to represent this entity.
A Mass Balance Summary configuration is an individually maintainable object, with a single optional instance deployed on each data object. It is serialized using XML (implemented with the Qt4 QDom classes), and that serialization is embedded in the data object (SimObj) Tcl serialization.
The Mass Balance Summary data model provides classes for lower-level objects, including a simple composite-pattern class hierarchy for the four levels of collection and slot reference items. Slot references are represented with SlotColRefs so that individual columns within, Table Series Slots could potentially be supported.
Subtasks:
Much of the mockup implementation is functional, but operates on shallow mockup data derived from the URGWOM reference model. Recoding the mockup implementation to operate on the real internal data model is a simple matter, and will support the development of the summary computations.
Subtasks:
Given an internal model implementation and a basic GUI to present the structure of the Summary configuration, the maintenance and computation of the summation slots can be implemented.
Subtasks:
The mockup implementation was based on an item-based QTreeWidget which has inherent performance limitations. This will need a full Qt4 abstract item model implementation with a custom delegate.
Subtasks:
Subtasks:
The mockup implementations of the five minor display lists (with item-based QTreeWidgets) are fairly complete. These will remain QTreeWidgets (i.e. abstract item-model based QTreeView implementations are not warranted). The mockup implementations need to be retooled to use the actual data model.
Subtasks:
| Task (3.2.x) |
Est. (days) |
Opt (days) |
Description |
| 1 | 2.0 | Internal Data Model | |
| 2 | 1.0 | Retooling Mass Balance Summary Dialog "Mockup" for actual data model. | |
| 3 | 2.5 | Summary Computation | |
| 4 | 2.5 | Abstract Item-Model based implementation of the main QTreeView | |
| 5 | 1.0 | Display unit type (flow and volume) and unit conversions. | |
| 6 | 1.0 | Summary Configuration Editing Operations | |
| 7 | 1.5 | Revision of supporting QTreeWidgets to use the actual data model. | |
| 8 | 1.5 | + 2.0 | Series Display Interfaces (Optional: Credit / Debit Annotations) |
| 9 | 1.0 | Integration / Finishing | |
| 10 | 2.0 | Testing and Feature Documentation | |
| 16.0 | + 2.0 | Totals |
--- (end) ---
