Mass Balance Summaries, RiverWare 6.2 -- Design Proposal

Author: Phil Weinstein, CADSWES.
Status:

• 12-07-2011: Initial writing completed; Ready for review.
• 12-08-2011: Added data model schematic

Requirements Document:

• MassBalanceTool_Rqmts.2011.11.14.pdf
• "The Upper Rio Grande Water Operations Team (URGWOM) would like a utility to help them check mass balance across many objects. This tool will be used in the calibration phase."

A "Mass Balance Summary" is an object containing a three-level hierarchy of physical series slot references. The values of the referenced series slots are summed in a positive or negative "sense", on a per-slot-group basis. (That is, the values of certain groups of slots will be subtracted from the "sum" rather than added). The sums at each of the three levels are represented as new series slots so that they can be accessed from RPL to make possible additional custom summary computations, e.g. for annual aggregation. The existing internal and GUI capabilities of a Computational Subbasin (SimObj) and AggSeriesSlot will be used to compose the summation series slots of a Mass Balance Summary.

The "Mass Balance Summary" contains:

1. A set of references to Simulation Objects (implemented as a user-defined Subbasin).
2. An ordered list of named "Budgets" (e.g. "Groundwater Budget"). Each Budget will have:
   • An AggSeriesSlot for the Budget. (The first column represents the Budget's sum).
   • An ordered list of named "Slot Groups" (e.g. "Inflow" or "SW Returns"). Loosely these are "slot entities" (representing physical entities). Each Slot Group will have:
     • An set of references to physical slots on Simulation Objects within the subbasin.
     • A "sense" flag ("+" or "-") indicating whether the values of contained physical slots represent a "credit" or "debit" for the computed sum.
     • An associated column within the Budget's AggSeriesSlot.
3. A "Summary Total" SeriesSlot, for the sum of all of the "Budgets" within the Mass Balance Summary.

The set of Mass Balance Summaries within a RiverWare model will be maintained using a new Mass Balance Summary Manager dialog. The manager will automatically create a Computational Subbasin for each new Mass Balance Summary. When creating a new Mass Balance Summary, the user will:

1. Specify a name for the Mass Balance Summary.
   • Optional: "Mass Balance" will automatically be appended to the name of the Mass Balance Summary provided by the user.
2. Select a set of Simulation Objects from the Workspace for the Summary's Subbasin.
3. Define a list of "Budgets" (names). The manager will place an AggSeriesSlot on the Computational Subbasin Object for each budget. The first column of the AggSeriesSlot will be for a computed sum.
4. Define a list of "Slot Groups" (names) for each Budget. A column in the Budget's AggSeriesSlot will be associated with each Slot Group.
5. Define a list of references to physical slots for each "Slot Group".

The Budget hierarchy for each Mass Balance Summary object will be maintained in a Mass Balance Summary Configuration dialog. It will be possible to simultanously show multiple such dialogs (for distinct Mass Balance Summary instances). Budgets, Slot Groups, and (references to) Slots will be presented in a three-level tree view. There will be functions for:

1. Copying selected Budgets and their Slot Groups between distinct Mass Balance Summaries (between distinct config dialogs).
2. Replicating one Budget's Slot Groups to other Budgets.

... neither of these operations will copy the references to physical slots under the source Slot Groups.

When selecting physical slots for a Slot Group, the GUS Slot Selector will be shown with a Subbasin Filter limiting the displayed slots to those on objects within the Subbasin. Within the Mass Balance Summary Config dialog, invalid items, e.g. references to slots on objects which are no longer in the subbasin, will be indicated as invalid, with a tooltip describing the problem.

It is an error for a particular physical slot to appear in more than one place within a Mass Balance Summary (maybe also within multiple Mass Balance Summaries?).

Possible usability aids:

• For the purpose of confirming completeness of a Mass Balance Summary configuration, we may want to present a list of physical series slots in the subbasin not already in the summary -- possibly filtered by criteria which represents which slots are to be included in the summary, if that criteria can be devised.
• It may be helpful to conditionally present a second, sortable listview enumerating all of the slots within the configuration, with additional columns showing each slot's containing Slot Group and Budget. (This feature could be combined with the former feature, with a toggle).

Question:

• For series slot references, are references to top-level slots sufficient? Or do we have to support references to particular AggSeriesSlot columns? (That's not hard to do if we plan on it).
• And do we need to support TableSeriesSlot Columns? (That's only a little harder to do).

Possible: We may want to color-code the backgrounds of ("+") and ("-") columns, e.g. ("+") columns could have a grey background.

---