Variable Mode Series Slots (working title) in RiverWare 6.3
Development Analysis / Phil Weinstein / 5-03-2012
Note: See also the Initial Analysis document, 2-17-2012 -- PDF

Document Status:

• 5-03-2012 (c): Ready for review, including development time estimates.

Working Assumptions / Decisions (to be reviewed)

At this time, we will explore the "reasonable general approach" described in the Initial Analysis document, limited to these provisions:

1. We will use these terms to describe this feature:
   • "Alternate Input Slot Modes" (of SeriesSlots):
     1. "Periodic Input Slot Mode"
     2. "Scalar Input Slot Mode"
         
2. Only single-column SeriesSlots will support the alternative "Periodic Input Slot" and "Scalar Input Slot" modes. That is, these modes will not be supported for multiple column AggSeriesSlots. (When reconfiguring an AggSeriesSlot on a DataObject, these modes will be turned off if the number of columns is increased to more than one column).
    
   
3. When a SeriesSlot is in an Alternate Input Slot Mode, any programmatic attempt to set a series value will result in a error, aborting a run, rather than reverting the slot into normal Series mode. This applies to normal solving (including method-based solutions), Rpl execution, and Input DMI operation.
    
4. Even if actual (redundant) series are maintained internally (TBD: see below), they will not be serialized within the model file, (reasonably enough).

Question: Should series be maintained internally, in memory, for Series Slots in an Alternate Input Slot Mode?

There are benefit tradeoffs of this decision with respect to run-time performance, memory footprint and development complexity.

Continuing to maintain fully-instantiated series for Series Slots in an Alternate Input Slot Mode reduces development complexity and avoids an additional run-time performance penalty when accessing the slot's values. Reading values from the Series Slot would work just as it does now -- no additional processing (and coding to implement additional processing) would be necessary. For slots in these modes, the series, or portion of the series would be recomputed from the internal Periodic or Scalar Slot definition only in these circumstances:

• When the user edits the internal Periodic or Scalar Slot configuration or values (at "GUI time").
• When the time range or time step size of the Series Slot is changed.
• After the Series Slot is loaded (i.e. from its internal Periodic or Scalar Slot serialization).

Furthermore, when the series values are computed (from the internal Period or Scalar Slots), there is no reason why they couldn't be flagged as (hard) Inputs. This would provide an implicit implementation of the prohibition of writing those values at run time (to the extent that that is sufficiently prevented -- it should be; Are there any exceptions to this?).

However, the alternative of NOT internally maintaining an internal series for Series Slots in an Alternate Input Slot Mode would require significantly less memory in long-series models. Using less memory, in and of itself, can have a performance benefit, i.e. with the possibility of less "paging" (at a couple levels of the computer memory architecture) and memory fragmentation. However, the following additional processing would be required:

• For ALL Series Slot value reads (on all Series Slots), and additional determination (flag check) of whether or not the particular Series Slot is in an alternate mode.
• For Series Slots in Periodic Input Slot Mode, all the processing required to determine which time internal the given timestep is in, plus the interpolation computation if values are to be interpolated (as opposed to just "looked up", i.e. a "step" function).

Also, explicit coding would be required to prevent writes to such slots to cause an automatic instantiation of the series.

The actual memory savings would be limited to those Series Slots which were actually IN an Alternate Input Slot Mode. In the scope if the whole model, this may actually be not very significant. While the percentage of series slots in a model having inputs can be large (e.g. in a particular large URGWOM model, 1598 of 3278 Series Slots have Run Period Inputs), it doesn't seem likely that many of those inputs would be expressible in these alternate forms.

Recommendation: (This seems pretty clear). The first option of continuing to instantiate series for Series Slots in the Alternate Input Slot Mode should initially be implemented. We could always choose later to develop the memory-saving option, but the benefit of that seems minor anyway, especially given the added development complexity.

Feature / Development Areas

(I'm going to tentatively assume that we will continue to maintain series for these modes, as recommended above).

(A) Series Slot Data Model

1. The SeriesSlot class would maintain optional internal instances of a Periodic Slot and a Scalar Slot.
2. These Periodic Slots and Scalar Slots should have a way of identifying their owning SeriesSlot. (We may be able to use the existing Slot::parentSlot field; the various uses of that field would need to be examined to determine if that is appropriate).
3. Support for an internal naming convention for these internal slots under a SeriesSlot. Those names should not be exposed in the user interface, but would be used for serialization.
4. Serialization (saving and loading) of a SeriesSlot's internal Periodic or Scalar slot.
5. Methods for computing the internal series based on the internal Periodic and Scalar Slots, plus invocations of those methods from the appropriate places. These mechanisms should generate value-changed callbacks from the Series Slot -- the specifics of which should be carefully considered, in terms of performance implications.
6. Propagation of the Periodic and Scalar slot configuration values (e.g. units and display properties, supporting also the extended configurability of slots on Data Object, e.g. slot name) to the containing SeriesSlot's configuration data members.
7. Automatic extension of the Series Slot time range when accessing a timestep not currently in the defined range, and recomputing the new timesteps from the internal Periodic or Scalar slot. When growing at the end, probably the Series should be extended for a reasonable number of extra timesteps, to reduce the number of allocations.
8. Determination of whether just having hard Input flags on the series is sufficient to protect against setting of those values from a "solution" algorithm or RPL execution. Otherwise, explicit checks in or around the SeriesSlot::assignStdValue() method. (Ideally, the effect of the prior item is applied as an initial step of value access, so that Input-flagged values will be found at the accessed timestep).
9. A check added to Import DMI operation to prevent the import of data to a SeriesSlot currently configured in an Alternate Input Slot Mode.

(B) GUI Support

1. Design, development and deployment of Slot Icons for Series Slots in an Alternate Input Slot Mode.
   ... see current slot icon set: http://cadswes2.colorado.edu/~philw/2011/icons/ObjAndSlotIcons.html#Slots
2. SeriesSlot Configuration Dialog enhancements to support Alternate Input Slot Mode selection, and display of the appropriate Slot configuration panel. This will involve some repackaging among the current slot configuration dialog GUIs.
3. In places where series slot data appears (e.g. SCT and the Edit Account Dialog), hooks (e.g. context menu operations) to display the underlying "Open" Periodic Slot or Scalar Slot dialog.
4. Modifications to the Open Periodic Slot and Scalar Slot dialogs to show only the parent slot's full name, and hooks to bring up the default series display dialog for that slot (Open Slot dialog, Edit Account dialog), and to cause the recomputation of the series at the appropriate times.
5. Optional: Enhancement to the "Find Input Slots" utility dialog to search for Series Slots currently in an Alternate Input Slot Mode.

(C) Enhancements to Report Generation Capabilities

1. When a Series Slot in an Alternate Input Slot Mode, generally its values should be presented within the report in its source form (Periodic Slot or Scalar Slot values).

Development Time Estimates

Task numbers to Feature, Development Areas above.
Estimate revision: 5-3-2012.

--- (end) ---