Variable Mode Series Slots (working title) in RiverWare 6.2 6.3
Initial Analysis / Phil Weinstein / 2-17-2012 -- PDF
Whether a particular input time series entity in a RiverWare model is specified as a series, or as a periodically varying value, or a constant (scalar) value is not fundamental to the physical entity being represented. In constructing a new model, or adapting an existing one for a different purpose, the user may want to freely switch the specification of input values for that entity between these different forms:
It would be desirable to switch the "mode" of a slot being used for inputs through a simple user configuration change. The user would then provide input values to that slot using the Open Slot Dialog for the particular mode.
(1) The myriad uses of slots by Engineering Objects are currently hard-coded to the particular type of Slot. There is not a set of slot value lookup methods (e.g. "what is the value on this slot at this date/time") that is common all slot types. From this software perspective, an existing physical series slot needs to continue to appear as a series slot, even if its values are provided by the user with the "periodic slot" user interface.
(2) The idea of specifying time series values with a periodic slot or scalar slot is limited to inputs. All generated (output) series are inherently full, actual unconstrained series. In general, any attempt to write a value at an arbitrary timestep to a slot which is currently specified as a periodic slot or scalar slot would need to be reported as an error. It would also be an error to attempt to import values via a DMI into a slot currently in either "periodic" or "scalar" mode. (Alternatively, a DMI import into a variable mode series slot could force it into "series" mode).
Given the first fundamental consideration above, the approach described below (here) is not practical. But understanding this may help in our thinking about the formulation we do present to the user.
All three slot types (series, periodic, scalar) are fundamentally time series definitions -- they all represent a value at a given time (down to a particular timestep resolution). The latter two are constrained cases. Ideally, "Series Slot" would be an abstract entity (an object which specifies a value at each of the timesteps within a defined timestep range). The three types of slots (series, periodic, scalar) would be dynamic subclasses of the abstract "Series Slot" class. (Dynamic: more flexible than C++'s classes: a given instance could be transformed into one of a different subclass). For reading a value from a Series Slot, a software "client" (user) of a slot wouldn't have to know which subclass a given instance is "in". In general, writing a value at a particular timestep to the periodic or scalar forms would either be an error, OR would "promote" the slot to a fully specified series slot.
This would work well if the clients of "Series Slots" were all written to this sort of abstract "Series Slot" interface, which is not the case. We really can't consider an approach which changes the slot programming interface currently used in Engineering Objects.
The series values made available to the internal RiverWare program interfaces from a Variable Mode Series Slot are effectively "read only" when in the "periodic" or "scalar" modes. It would be reasonable to enhance the existing SeriesSlot class to optionally support hidden PeriodicSlot and ScalarSlot child instances ("Value Source slots") from which the SeriesSlot's series is computed.
In general, the Open Slot Dialog and Slot Configuration Dialog for a Variable Mode Series Slot will be those corresponding to the slot's current mode. In the "periodic" and "scalar" modes, it will actually be a child Value Source slot which is actually displayed -- but with the name of the top-level SeriesSlot.
When in "periodic" and "scalar" modes, the series data will be written (and writable) from only the internal "serialization" computation of the Value Source slot. Where the values are shown as a series (e.g. in the SCT) -- in these modes -- the values will be "read-only" (and shown with the cross-hatch ornamentation). Also, when attempting to set values from outside of that "serialization" computation, an error will be reported.
A Variable Mode Series Slot is just a Series Slot for which this functionality is enabled, as a setting on individual SeriesSlots. It's not a special subclass of SeriesSlot. As such, instead of referring to these slots as "Variable Model Series Slots", we would instead refer to this feature as a special mode (or modes) of SeriesSlots. Possibly:
These modes are mutually exclusive with RPL Expression SeriesSlot support. RPL Expression slots would not support these modes.
The following table shows the numbers of the different types of slot entities currently defined in RiverWare Engineering Objects which are relevant to this discussion. These are the numbers of slot proxy instances on the Engineering Object prototype objects. (See also a table showing counts for all Slot types supported by slot proxies).
| Slot Type | Count | Single Col |
Multi Col |
| Series Slot | 1570 | ||
| AggSeries Slot | 358 | 311 | 47 |
| Periodic Slot | 138 | 130 | 8 |
| Scalar Slot | 190 |
The general approach described above applies to adding variable mode support for existing SeriesSlots. Single-column AggSeries slots could also readily be supported. This most basic support would cover over 80% of the physical slots to which this feature could apply.
Multiple column AggSeries Slots (of which there are 47 in RiverWare) pose a complication mostly for the presentation of the Open Slot dialog. (We don't currently show an individual AggSeries Slot column -- a SeriesSlot -- in its own Open Slot Dialog). For periodic mode, if all the AggSeries Slot column slots were to have the same periodic time configuration, then the Value Source slot would just be multiple-column Periodic Slot (without a numeric dimension). Since this is a new capability, there is no problem with choosing to impose that limitation; it would still be possible for each AggSeries Slot to have a distinct timestep range. We could just forgo scalar slot mode support for multiple-column AggSeries Slots, as a single row in a periodic definition would be equivalent.
Providing variable mode support for existing Periodic and Scalar slots would require an entirely different solution, basically doubling the complexity of this feature. It would be more reasonable to just change the most desirable periodic and scalar slot candidates (if any) to series slots. (Note that there are only 130 single-column Periodic Slots defined in RiverWare). This change to existing periodic slots would require the addition of relevant legacy migration code.
We've been thinking of showing Periodic Slots as series within series displays along with other series -- specifically in the SCT. This would be the default (automatic) behavior of Series Slots in period input slot mode. Of course, this would also apply to any Periodic Slots migrated to Series Slots once this variable mode series slot capability is available.
--- (end) ---