Time Aggregation Series Slots in RiverWare 6.3 / Feature Document

(0.1) Document Status:

(0.2) Contents

    

(1.0) Overview

Time Aggregation Series Slots are a new type of series slot which temporally aggregates any other single series slot in the RiverWare model. They are created on data objects by the user and can be recomputed manually or automatically at the end of a run.

The configuration of a Time Aggregation Series Slot includes the following properties:

*The water year is defined on a model-wide basis as beginning in a particular month -- the "Water Year Start Month". It is set by the user in the Run Parameters dialog. This is a partial implementation of a water year determining the timestep values which go into a particular annual value for the Time Aggregation Series Slot computation. The resulting annual series is still nominally (technically, incorrectly) identified as a calendar year (ending on December 31). Water years are named by the year in which the water year ends, i.e. a water year from October 2000 through September 2001 is the "2001" water year.  This is consistent with the computations done by the RDF Annualizer.

The ability to duplicate a Time Aggregation Series Slot for the same referenced slots on multiple other "similar" objects is provided.

(2.0) Creating a new Time Aggregation Series Slot

    

Time Aggregation Series Slots are created by the user on data objects. This is done by selecting the "Add Time Aggregation Series Slot" item from the Open Data Object dialog's "Slot" menu. (See image to the right).

 

            Slot type icon for Time Aggregation Series Slots.

 

Once created, the user can double click on the new Time Aggregation Series Slot item in the Open Object Dialog to configure the slot. Minimally, the following two properties should be set by the user:

  1. The name of the new Time Aggregation Series Slot -- edited at the top of the Open Slot dialog.
     
  2. The identity of the "referenced" series slot -- picked with the slot selector by clicking on the "Select Slot ..." button. See below.


 


(2.1) Configuration settings supported in the Open Slot Dialog.

In the Open Slot Dialog's aggregation control panel, the "Function" combo box allows the user to select the aggregation function to be used.

In all computations "NaN" values are ignored. However, the presence of a NaN in any timestep after the start-of-run can optionally cause an error to be generated, depending on a setting in the configuration dialog, see below.

This panel contains push buttons to:

  1. Show the configuration dialog -- for additional configuration settings.
  2. Show the Open Slot Dialog for the referenced slot (i.e. the series slot being aggregated).
  3. Manually recalculate the aggregation series data.

A description of the current aggregation period is shown (to the right of the "configure" icon button). This is set in the Time Aggregation Series Slot Configuration Dialog:

     

(2.2) Configuration settings supported in the Time Aggregation Series Slot Configuration Dialog.

    

Apart from the general configuration controls shown in the Time Aggregation Series Slot Configuration Panel in the Open Slot Dialog, additional controls are available in a separate popup dialog which is shown by clicking on the "configure" (gear) icon. (See above).

As described in the Overview section, three aggregation periods are supported. The type of aggregation period used for the particular Time Aggregation Series Slot is set in this configuration dialog, with the following choices available:

The use of the "Water Year" used in the RiverWare model is described in the subsequent section. (See also the Overview section).

The "Evaluate at end of run" checkbox controls whether or not this Time Aggregation Series Slot is automatically evaluated (recalculated) at the end of a RiverWare run. The "end of run" evaluations of Time Aggregation Series Slots are performed after all "end of run" RPL Expression Slot evaluations. (So, it would be reasonable for a Time Series Aggregation Slot to aggregate an "end of run" RPL Expression Series Slot).

The "Post error on encountering NaN" checkbox controls whether an error is reported if a NaN (undefined series timestep value) is encountered during the aggregation calculation. This applies only to NaNs after the beginning-of-run timestep. (Errors will not be reported for pre-simulation timestep NaNs).

(2.3) Annual Aggregation support for Non-Calendar Water Years

    

One of the supported aggregation modes is aggregation to "Water Years" starting in a user-specified month.

The Water Year Start Month is a model-wide setting, set in the Simulation Run Parameters dialog, accessible from the Run Control Dialog (as mentioned in text shown in the Time Aggregation Series Slot Configuration Dialog).

See also the note about Water Year support in the Overview section.

(3.0) Creating Similar Time Aggregation Series Slots for Different Objects

In a single operation, the user can duplicate a Time Aggregation Series Slot for the aggregation of the referenced series slot on multiple other selected simulation objects. For example, if a given time aggregation slot is annually summing the Energy slot on a power reservoir, similar aggregation slots can be created for all other power reservoirs in the RiverWare model, in a single operation.

When a single Time Aggregation Series Slot item is selected within an Open Data Object Dialog's slot list -- if that aggregation slot is configured with a referenced series slot -- the "Create Similar Slot for Different Objects..." operation under the Slot menu is enabled. Activating that menu item brings up the simulation object selector dialog where multiple objects can be selected. The selector is initialized to show objects of the same type as the object containing the reference slot (e.g. in this example, Power Reservoirs). Ultimately though, the user can select a broader range of simulation objects.

 

Technical note: Slot class hierarchy "hooks" were devised such that this operation could be implemented also for Statistical Table Slots, which also represent a computation based on a single referenced series slot. See these three virtual Slot class methods, and their implementation in the SeriesSlot class:
  • virtual bool supportsReferencedSlotParam() const { return false; }
  • virtual Slot* referencedSlotParam() const { return NULL; }
  • virtual Slot* cloneForObjForRefSlotParam (SimObj*, okstat&) const { return NULL; }

The names of the new slots are devised as follows:

If the originally selected time aggregation slot's name contains the name of the referenced slot's containing object, then the new names are that name, with the original containing object name replaced by the new selected objects. In the following example, the original time aggregation slot named "Annual BlueMesa Energy" is aggregating the "BlueMesa.Energy" slot (on the BlueMesa power reservoir).

However, if the originally selected time aggregation slot's name does not contain the name of the referenced slot's containing object, no direct name substitution is possible. Instead, the names of the new selected objects are appended to the slot name for the new slots. In this example, the name of the originally selected time aggregation slot is "Annual Res Energy", and it aggregates the "BlueMesa.Energy" slot. Note that the set of newly created time aggregation slots includes one also for the "BlueMesa" power reservoir, since that reservoir had been included in the selection made by the user within the object selector (in this example).

(4.0) Showing Multiple Time Aggregation Series Slots in an SCT

As a previously available RiverWare feature, the user can display the set of slots on any simulation object in an SCT. For series slots on an object, this capability is limited to the series slots having the same timestep size. (In the examples shown above, all series slots have an annual timestep).

The following SCT is created from the Open Object Dialog using the Slot menu's "SCT >> Show All Slots in New SCT..." operation.

--- (end) ---