Fixed cnrecs.def comments; enhanced documentation

Author: chipbarnaby

doc/src/records/accumulator.md

@@ -1,17 +1,51 @@
 # ACCUMULATOR
 
-An ACCUMULATOR object is a user-defined "device" that records arbitrary values computed during the CSE simulation.
+An ACCUMULATOR is driven by arbitrary subhourly expression value computed during the CSE simulation and calculates minimum, maximum, mean, and sum values for hour, day, month, and year intervals.  In addition, timestamps are retained for the minimum and maximum values. ACCUMULATORs are useful for summarizing and reporting values for which there is not built-in accounting (for example, ZNRES or RSYSRES).  One common use case is for reporting hour average values of internal variables that vary subhourly.
 
-TODO: expand description and example
+ACCUMULATORs are "observing" devices -- they have no effect on the CSE building model or calculations.  ACCUMULATOR values must be reported using user-defined REPORTs or EXPORTs.
 
-ACCUMULATOR results must be reported using user-defined REPORTs or EXPORTs.  For example --
+As a simple example, a report of monthly outdoor drybulb temperatures can be generated as follows --
 
-    REPORT rpType=UDT rpFreq=Month rpDayBeg=Jan 1 rpDayEnd=Dec 31
-        REPORTCOL colHead="mon" colVal=$Month colWid=3
-        REPORTCOL colHead=" Sum" colVal=@Accumulator[ 1].M.acmSum colDec=0 colWid=10
-        REPORTCOL colHead="Average" colVal=@Accumulator[ 1].M.acmMean colDec=0 colWid=10
+    ACCUMULATOR "ACTDB" acmValue=$tdbosh
+
+    REPORT "TODB" rpType=UDT rpFreq=Month rpTitle="Outdoor drybulb temp (F)"
+      REPORTCOL colHead="Mon" colVal=$Month colWid=3
+      REPORTCOL colHead="Min" colVal=@Accumulator[ "ACTDB"].M.acmMin colDec=2 colWid=6
+      REPORTCOL colHead="Mean" colVal=@Accumulator[ "ACTDB"].M.acmMean colDec=2 colWid=6
+      REPORTCOL colHead="Max" colVal=@Accumulator[ "ACTDB"].M.acmMax colDec=2 colWid=6
+    REPORT rpType=UDT rpFreq=Year rpHeader=No
+      REPORTCOL colVal="Yr" colWid=3
+      REPORTCOL colVal=@Accumulator[ "ACTDB"].Y.acmMin colDec=2 colWid=6
+      REPORTCOL colVal=@Accumulator[ "ACTDB"].Y.acmMean colDec=2 colWid=6
+      REPORTCOL colVal=@Accumulator[ "ACTDB"].Y.acmMax colDec=2 colWid=6
+
+Resulting output --
+
+      Outdoor drybulb temp (F)
+
+      Mon    Min   Mean    Max
+      --- ------ ------ ------
+        1  28.22  46.87  60.08
+        2  32.00  49.26  69.98
+        3  42.08  60.79  91.40
+        4  34.70  58.13  79.16
+        5  44.42  67.07  97.88
+        6  50.36  73.43 107.96
+        7  55.04  74.02 101.48
+        8  53.60  74.99 104.18
+        9  48.92  69.24  97.52
+       10  47.84  64.00  98.42
+       11  32.54  54.47  77.00
+       12  28.04  46.58  64.04
+
+       Yr  28.04  61.65 107.96
+
+Generalizing what is illustrated, probing @accumulator[ ].H yields statistics for the current hour, .D for the current day, .M the current month, and .Y for the year (or, more precisely, the full run, which may or may not be a full year).
+
+A complete list of the available statistics for each interval is found in the ACCUMULATOR probe documentation.
+
+Note: The initial version of ACCUMULATOR contains unresolved bugs related to the timing of the determination of acmValue.  In some cases, acmValue is set to the expression value from the prior substep.  This is being investigated.
 
-(Note use of colHead=" Sum" (not colHead="Sum") to avoid a CSE parsing quirk.  See REPORTCOL.)
 
 **acmName**
 
@@ -26,7 +60,7 @@ Name of ACCUMULATOR: required for referencing in reports.
 
 **acmValue=*float***
 
-The value being accumulated.  Generally expression.
+The value being accumulated.  Generally expression with subhourly variability.
 
 <%= member_table(
   units: "any",

src/CNRECS.DEF

@@ -1320,9 +1320,11 @@ RECORD XSURF "xsurf sub" *SUBSTRUCT	// for PRI, SFI, XSRAT.
     *mh FRAC sco    // window: SMSO: Solar Heat Gain Coef multiplier, shades Open
     *mh FRAC scc    // window: SMSC: Solar Heat Gain Coef, shades Closed
     *r *nest SBC xs_sbcI	// inside (zone side) surface boundary conditions
+                            //   ASHWAT windows: BCs at inside face of inside layer (glazing or shade; frame excluded, see xs_frmSbcI)
     *r *nest SBC xs_sbcO	// outside (ambient or adjacent zone) surface boundary conditions
+                            //   ASHWAT windows: BCs at outside face of outside layer (glazing, screen, or shade; frame excluded, see xs_frmSbcO)
     *r *nest SBC xs_frmSbcI	// ASHWAT windows: frame inside (zone side) surface boundary conditions
-    *r *nest SBC xs_frmSbcO	// ASHWAT windows: frame outside (ambient (or adjacent zone?)) surface boundary conditions
+    *r *nest SBC xs_frmSbcO	// ASHWAT windows: frame outside (ambient) surface boundary conditions
 
     *i FENMODELCH xs_fenModel	// fenestration model: user input
     *i FRAC xs_SHGC				// rated SHGC of assembly
@@ -5564,18 +5566,18 @@ DBL acmSum      // sum of values in interval
 SI acmMinDayOfYear      // day of year on which min occurs, 1-365
 SI acmMinDayOfYearST    // day of year (standard time) on which min occurs, 1-365
                         //  can differ from acmMinDayOfYear iff Top.DT=Yes
-SI acmMinHour           // hour of day at which min occurs, 1-24
-SI acmMinHourST         // hour of day (standard time) at which min occurs, 1-24
+SI acmMinHour           // hour of day at which min occurs, 0-23
+SI acmMinHourST         // hour of day (standard time) at which min occurs, 0-23
                         //  can differ from acmMinHour iff Top.DT=Yes
-SI acmMinSubhour        // subhour within hour at which min occurs, 1-Top.tp_nSubSteps
+SI acmMinSubhour        // subhour within hour at which min occurs, 0 - Top.tp_nSubSteps-1
 
 SI acmMaxDayOfYear      // day of year on which min occurs, 1-365
-SI acmMaxDayOfYearST    // day of year (standard time) on which max occurs, 1-365
+SI acmMaxDayOfYearST    // day of year (standard time) on which max occurs, 0-23
                         //  can differ from acmMaxDayOfYear iff Top.DT=Yes
-SI acmMaxHour           // hour of day at which min occurs, 1-24
-SI acmMaxHourST         // hour of day (standard time) at which max occurs, 1-24
+SI acmMaxHour           // hour of day at which min occurs, 0-23
+SI acmMaxHourST         // hour of day (standard time) at which max occurs, 0-23
                         //  can differ from acmMaxHour iff Top.DT=Yes
-SI acmMaxSubhour        // subhour within hour at which min occurs, 1-Top.tp_nSubSteps
+SI acmMaxSubhour        // subhour within hour at which min occurs, 0 - Top.tp_nSubSteps-1
 
 *END		// ACCUMULATOR_IVL
 //=============================================================================