Window solar gain accounting / ACCUMULATOR improvements

doc/src/cse-user-manual.yaml

@@ -66,6 +66,7 @@ sections:
   - [2, "records/dhwmeter.md"]
   - [2, "records/afmeter.md"]
   - [2, "records/loadmeter.md"]
+  - [2, "records/accumulator.md"]
   - [2, "records/zone.md"]
   - [2, "records/gain.md"]
   - [2, "records/surface.md"]

doc/src/records/accumulator.md

@@ -0,0 +1,86 @@
+# ACCUMULATOR
+
+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.
+
+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.
+
+As a simple example, a report of monthly outdoor drybulb temperatures can be generated as follows --
+
+    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.
+
+
+**acmName**
+
+Name of ACCUMULATOR: required for referencing in reports.
+
+<%= member_table(
+  units: "",
+  legal_range: "*63 characters*",
+  default: "*none*",
+  required: "Yes",
+  variability: "constant") %>
+
+**acmValue=*float***
+
+The value being accumulated.  Generally expression with subhourly variability.
+
+<%= member_table(
+  units: "any",
+  legal_range: "",
+  default: "",
+  required: "Yes",
+  variability: "subhourly") %>
+
+
+**endACCUMULATOR**
+
+Indicates the end of the ACCUMULATOR definition. Alternatively, the end of the definition can be indicated by the declaration of another object or by END.
+
+<%= member_table(
+  units: "",
+  legal_range: "",
+  default: "*none*",
+  required: "No",
+  variability: "constant") %>
+
+**Related Probes:**
+
+- @[accumulator](#p_accumulator)

doc/src/records/door.md

@@ -254,7 +254,7 @@ Interior convection coefficient adjustment factor.  When drInHcModel=INPUT, hc=d
 
 **drInHcFrcCoeffs=*float array***
 
-Specifies 3 coefficients for an alternative inside surface forced convection model (applicable only for drInHCModel=UNIFIED).  When given, the inside surface forced convection coefficient for this surface is derived as follows:
+Specifies 3 coefficients for an alternative inside surface forced convection model (applicable only for drInHcModel=UNIFIED).  When given, the inside surface forced convection coefficient for this surface is derived as follows:
 
       hcFrc = hConvF * (drInHcFrcCoeffs[ 1] + drInHcFrcCoeffs[ 2] * ACH ^ drInHcFrcCoeffs[ 3])
 

doc/src/records/exportcol.md

@@ -46,6 +46,8 @@ Value to show in this position in each row of export.
 
 Text used for field name in export header.
 
+Note: Due to quirk (or bug?) in CSE parsing, setting *colHead* equal to "sum", "all", or "all_but" (case-insensitive) will trigger an error message along the lines of "'SUM' cannot be used here."  Adding a space avoids this issue.  For example, colHead = " Sum" is accepted.
+
 <%= member_table(
   units: "",
   legal_range: "",

doc/src/records/reportcol.md

@@ -41,6 +41,8 @@ Value to show in this column of report.
 
 Text used for column head.
 
+Note: Due to quirk (or bug?) in CSE parsing, setting *colHead* equal to "sum", "all", or "all_but" (case-insensitive) will trigger an error message along the lines of "'SUM' cannot be used here."  Adding a space avoids this issue.  For example, colHead = " Sum" is accepted.
+
 <%= member_table(
   units: "",
   legal_range: "",

src/CNRECS.DEF

@@ -1269,11 +1269,11 @@ RECORD XSURF "xsurf sub" *SUBSTRUCT	// for PRI, SFI, XSRAT.
 	*declare "XSURF& Copy( const XSURF* pXS, int options=0);"
 	*declare "RC xs_Validate( int options=0);"
 	*declare "SBC& xs_SBC( int si) { return si ? xs_sbcO : xs_sbcI; }"
+	*declare "SBC& xs_FrmSBC( int si) { return si ? xs_frmSbcO : xs_frmSbcI; }"
 	*declare "const char* xs_Name() const;"
 	*declare "int xs_CanHaveExtSlr() const;"
 	*declare "RC xs_SetUNom();"
 	*declare "float& xs_AbsSlr( int io) { return xs_SBC( io).sb_absSlr; }"
-	*declare "float xs_AreaGlazed() const;"
 	*declare "void xs_SetRunConstants();"
 	*declare "void xs_AccumZoneValues();"
 	*declare "void xs_sbTest();"
@@ -1298,7 +1298,9 @@ RECORD XSURF "xsurf sub" *SUBSTRUCT	// for PRI, SFI, XSRAT.
     *z SI xs_ty		// type CTEXTWALL, CTINTWALL, CTWINDOW, CTMXWALL, CTPERIM, CTKIVA set by cult or code.
 
 	// inputs.  *r's where set by topCkf in at least some cases.
-    *r AREA_GZ xs_area	// (net) area, sf.  Reflects window multiplier.
+    *r AREA_GZ xs_area	// (net) area, ft2.  Reflects window multiplier.
+    *r AREA_GZ xs_areaGlz   // glazed area, ft2. nz iff window
+                            // reflects window multiplier and frame fraction
     *r ANGLE azm 		// azimuth (radians, 0 = North, Pi/2 = East)
     *r ANGLE tilt 		// tilt (radians, 0 = horiz up, Pi/2 = vert.
     *r *array 3 FLOAT xs_dircos	// outward normal direction cosines for given azm/tilt
@@ -1318,7 +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) surface boundary conditions
 
     *i FENMODELCH xs_fenModel	// fenestration model: user input
     *i FRAC xs_SHGC				// rated SHGC of assembly
@@ -1363,16 +1369,22 @@ RECORD XSURF "xsurf sub" *SUBSTRUCT	// for PRI, SFI, XSRAT.
 
     *r TI iwshad 		// 0 if none or subscr in WSHADRAT of overhang/fin info for a shaded window
     *r TI xs_msi		// 0, or mass (MsR) subscript for CTMXWALL.
-    *array XSMXTLRB *h *e
-		FLOAT xs_tLrB	// layer boundary temps re probes
-						// populated at end of hour
-
-// solar gain distributions: [partly] based on SGDIST inputs
+
+    // solar gain distributions: [partly] based on SGDIST inputs
     *r SI nsgdist	 		// Number of SG distributions
     // SGDIST sgdist[ HSMXSGDIST]:
     *array HSMXSGDIST	// =8 (2-95), cndefns.h. explicit solar gain distribs
        *r			// min variation here: no members set at input time
        *nest SGDIST sgdist	// solar gain distribution (struct just above).  set: cncult3.cpp:cnuSgDist().
+
+    // runtime values
+    *s *e FLOAT xs_glzTrans     // ASHWAT windows: transmitted solar gain, Btuh/ft2 (w/o cavity absorp adjustment)
+    *s *e FLOAT xs_glzInward    // ASHWAT windows: inward flowing convective and LW radiant gain to zone, Btuh/ft2
+
+    *array XSMXTLRB *h *e
+		FLOAT xs_tLrB	// layer boundary temps re probes
+						// populated at end of hour
+
 *END		// XSURF
 //=============================================================================
 RECORD PRI "perimeter" *RAT	// perimeter input RAT
@@ -1441,7 +1453,7 @@ RECORD SFI "surface" *RAT	// opaque surface / door / window input info RAT
  //window only
     *i LEN_GZ sf_width 		// width and height: used to compute shading,
     *i LEN_GZ sf_height		//  ... and to compute area b4 mutliplier.
-    *i FLOAT_GZ mult		// area multiplier (for multiple identical windows)
+    *i FLOAT_GZ sf_mult		// area multiplier (for multiple identical windows)
  //derived/internal
     *r TI xi		// subscript in runtime XSRAT, to facilitate access by probers 1-92
     *r TI sf_msi	// 0 or MSRAT MsR subscr which will be used if delayed model
@@ -2453,7 +2465,8 @@ RECORD ZNR "zone" *RAT	// zone runtime info RAT.  Set mainly from separate ZNI
     *r DBL zn_BGWallPA5		// sum (perim*a5)
 
 // ZNR loads runtime: hourly q's for  Tz = (a + q)/b.
-	*h *e DBL qSgTot			// hour total solar gain to some
+	*h *e FLOAT qSgTot			// hour total solar gain to zone, Btuh
+                                //  = zn_sgTotTarg.st_tot
     *h *e *nest SGTARG zn_sgTotTarg	// hourly part of s g total (Btuh) for zone: hourly mass insides.
 								// Added to in cnloads.cpp:loadsHour via pointers in SgR entries made monthly
 								// in cgsolar.cpp per info in XSURFs made in cncultn.cpp. Used: cnztu.cpp re results qSlr
@@ -2498,10 +2511,12 @@ RECORD ZNR "zone" *RAT	// zone runtime info RAT.  Set mainly from separate ZNI
     *s *e *nest SGTARG zn_sgAirTarg   // Solar gain (Btuh) target (float) for zone air: all sun thru windows not SGDIST'd to a mass.
 								//  Added to in cnloads.cpp:loadsSubhr via pointers in SgR entries made monthly
 								//  in cgsolar.cpp per info in XSURFs made in cncultn.cpp. Used: cnloads.cpp re aqLdSh. */
-	*s *e DBL qSgTotSh
+
     *s *e *nest SGTARG zn_sgTotShTarg	// subhourly part of s g total (Btuh) for zone: air + mass insides.
 								//  Added to in cnloads.cpp:loadsSubhr via pointers in SgR entries made monthly
 								//  in cgsolar.cpp per info in XSURFs made in cncultn.cpp. Used: cnztu.cpp re results qSlr */
+    *s *e FLOAT qSgTotSh        // Total solar gain to room, including transmitted and inward flowing fraction, Btuh
+                                //   = zn_sgTotShTarg.st_tot + inward flowing from ASHWAT glazing
     *h *hide DBL aMassSh  		// Subhourly mass portion of zn_aqLdHr: sum ha*T to subhourly masses exposed to zone. note 1.
     *s *hide DBL zn_uaInfil 	// Infiltration UA (uval * area, === heat cap flow), this hour, for aq-,bLdSh and zone w.  note 2.
 								// === heat capacity of entering air (Btuh/F).  Divide by top.airxO for cfm.
@@ -5532,6 +5547,58 @@ RECORD GAIN "gain" *RAT   	// (zone internal) Gain input and runtime
 								//   note includes _TOTAL and _UNKNOWN
 *END			// GAIN
 //=============================================================================
+RECORD ACCUMULATOR_IVL "accumulator interval sub" *SUBSTRUCT  // substruct for one accumulator for one interval
+*prefix acm_
+
+*declare "void acm_Copy( const ACCUMULATOR_IVL* src);"
+*declare "void acm_PopulateSubhr( float value);"
+*declare "void acm_Accum( const ACCUMULATOR_IVL* sIvl, bool firstFlg, bool lastFlg, int options=0);"
+
+// NOTE: visible prefix used, not *prefix
+//       WHY: the name "sum" is treated as reserved and rejected.
+//            Visible "acm" prefixes solve avoid that
+INT acmCount    // total # of subhrs included
+
+FLOAT acmMin    // min value seen in interval
+FLOAT acmMean   // mean value seen in interval
+FLOAT acmMax    // max value seen in interval
+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, 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, 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, 0-23
+                        //  can differ from acmMaxDayOfYear iff Top.DT=Yes
+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, 0 - Top.tp_nSubSteps-1
+
+*END		// ACCUMULATOR_IVL
+//=============================================================================
+RECORD ACCUMULATOR "accumulator" *RAT 
+*prefix acm_
+
+    *declare "RC acm_CkF( int options);"
+
+    // NOTE: visible prefix used, not *prefix
+    //       WHY: the name "sum" is treated as reserved and rejected.
+    //            Visible "acm" prefixes solve avoid that
+    *s *e FLOAT acmValue;              // value being accumulated
+                                        // generally set via probe 
+
+    *y *e *nest ACCUMULATOR_IVL Y   	// run (aka year or annual)
+    *m *e *nest ACCUMULATOR_IVL M   	// current month
+    *d *e *nest ACCUMULATOR_IVL D   	// current day
+    *h *e *nest ACCUMULATOR_IVL H   	// current hour
+*END		// ACCUMULATOR
+//=============================================================================
 RECORD MTR_IVL "meter interval sub" *SUBSTRUCT  // substruct for one meter for one interval for entire building
  // use results