Time Aggregation Series Slot Fixes / Gnats 5614
Bug Number: 5614
Release notes (y/n): Yes
For Release Nums: 6.7

Gnats 5614: Annual Aggregation time series slots are not correctly summing
monthly flows in units of AF/month.

Note: These fixes are apart from another problem discovered in the course of
this fix: We were not correctly converting standard flow units within an
annual series to a "per month" unit. That problem was addressed in
parallel to the main "5614" dysfunction and related enhancements (e.g.
extending the Time Aggregation Series Slot to additional timestep sizes).
See the current state of analysis for that conversion problem, here:

  http://cadswes2.colorado.edu/~philw/2015/UnitConvert/Analysis.html
  http://cadswes2.colorado.edu/~philw/2015/UnitConvert/UnitMgrConversionMethods.png
  http://cadswes2.colorado.edu/~philw/2015/bugs/5614/OneAcreFootPerMonth-WeighedAveComp.png

That problem is also illustrated in this annotated development screenshot,
which also serves the purpose of illustrating some of the fixes in THIS
COMMIT (described below).

   http://cadswes2.colorado.edu/~philw/2015/bugs/5614/2015-03-25/OneM3perMonth-AveAnalysis.png

---------------------------------------------------------------
Changes to the Time Aggregation Series Slot in this commit are:
---------------------------------------------------------------

(1) The calculations for Sum and Ave, both involving the summation of
contiguous groups of timesteps within the source series, now perform a
_weighted sum_ (weighted by the number of seconds in each timestep) -- IF
the source slot's unit type is a RATE (e.g. flow, i.e. having a "perTime"
factor).  The 'weightVec' vector parameter was added to this private
method:

   okstat computeAggSlotValue (SeriesSlot* targSlot,
                               const Date_Time& dt,
                               bool sourceUnitTypeIsRate,
                               const QVector<double>& inpValVec,
                               const QVector<double>& weightVec,
                               int agElemCnt,
                               bool inputOnly,
                               QMap<unsigned int, int>& inputStateMap) const;

See also similar treatment in the lower-level local functions,
aggSum() and aggAve().

(2) Related ... in the aggSum() local function, if a RATE is being summed,
we number of terms being summed is factored back out.  This was a FIX to an
incorrect calculation.  We had incorrectly been showing, for example, the
sum of 1 acre-ft/month over twelve months as 12 acre-ft/month.  The result
should be 1 acre-ft/month -- effectively, actually, the average.  But we are
(elsewhere, see below) choosing to show such a sum in "acre-ft/year".  (And
of course, the result would then be 12 acre-ft/year).

(3) (as inferred in the prior item) ... When a SUM is shown, we now attempt
to change the UNIT of the Time Aggregation Series Slot to have a "perTime"
factor matching the aggregate timestep size (e.g. annual).  This is done
with a change to the following function ...

   void SeriesSlot::TimeAggSpec::updateOwnerSlotUnits()

... making use of this new UnitMgr method:

   // return variant of the given unit for the specified perTime step size.
   // An empty string is returned if the desired rate unit is not found.
   QString UnitMgr::unitVariantForStepSize (const QString& refUnitName,
                                            const DeltaTime& stepSize);

... and an enhancement to the Unit definition (and a change to the "units"
file) to be specific about the size of the "perTime" factor for rates, even
for the various "fixed" (actual time unit) "perMonth" units.  So, "Fixed" in
the units file was replaced by "perSec" or "perMin" or "perHour" or
"perDay".  This is in addition to the previously supported "perMonth" and
"perYear" values.  This now are encoded with this enumerated type, a
property of each Unit instance:

   typedef enum {
      NonRate = 0,
      perSec,
      perMin,
      perHour,
      perDay,
      perMonth,
      perYear
   } unit_duration;

NOTE: the changed "units" file (Units/units) with replacement of "Fixed"
with the more precise "perTime" designations needs to be copied to the
executable directory OR the directory pointed to by the RIVERWARE_HOME_67
environment variable -- though not doing so (i.e. continuing to use the old
one) does behave reasonably well.