Merge pull request #108 from cse-sim/reportinfil

AFMETER fixes / documentation / test case

Author: chipbarnaby

doc/src/cse-user-manual.yaml

@@ -43,6 +43,7 @@ sections:
   - [2, "records/glazetype.md"]
   - [2, "records/meter.md"]
   - [2, "records/dhwmeter.md"]
+  - [2, "records/afmeter.md"]
   - [2, "records/zone.md"]
   - [2, "records/gain.md"]
   - [2, "records/surface.md"]

doc/src/records/afmeter.md

@@ -0,0 +1,28 @@
+# AFMETER
+
+An AFMETER object is a user-defined "device" that records zone air flows as simulated by CSE. The user defines AFMETERs and assigns them to zones (see ZONE znAFMtr).
+
+Air flow is recorded in standard air cfm (density 0.075 lb/ft3) at subhour, hour, day, month, and year durations.  Flows are categorized according to IZXFER izAFCat.
+
+Note that *only* AirNet flows are recorded.  
+
+
+**afMtrName**
+
+Name of meter: required for assigning energy uses to the meter elsewhere.
+
+  **Units**   **Legal Range**   **Default**   **Required**   **Variability**
+  ----------- ----------------- ------------- -------------- -----------------
+              *63 characters*   *none*        Yes            constant
+
+**endAFMeter**
+
+Indicates the end of the meter definition. Alternatively, the end of the meter definition can be indicated by the declaration of another object or by END.
+
+  **Units**   **Legal Range**   **Default**   **Required**   **Variability**
+  ----------- ----------------- ------------- -------------- -----------------
+                                *N/A*         No             constant
+
+**Related Probes:**
+
+- @[afmeter](#p_afmeter)

doc/src/records/izxfer.md

@@ -76,6 +76,36 @@ Choice determining interzone ventilation
 
   -----------------------------------------------------------------
 
+**izAFCat=*choice***
+
+Choice indicating air flow category used *only* for recording air flow results to an AFMETER.  izAFCat has no effect for non-AIRNET IZXFERs.  izAFCat is not used unless the associated ZONE(s) specify znAFMtr.
+
+
+Choices are:
+
+  ----------   -------------------------------------------
+  InfilEx      Infiltration from ambient
+  VentEx       Natural ventilation from ambient
+	FanEx        Forced ventilation from ambient
+	InfilIz      Interzone infiltration
+	VentIz       Interzone natural ventilation
+	FanIz        Interzone forced ventilation
+	DuctLk       Duct leakage
+	HVAC         HVAC air
+  ---------    -------------------------------------------
+
+Default values for izAFCat are generally adequate *except* that natural ventilation IZXFERs are by default categorized as infiltration.  It is thus recommended that izAfCat be omitted except that ventilation IZXFERs (e.g. representing openable windows) should include izAfCat=VentEx (or VentIz).
+
+----------------------------------------------------------------
+  **Units** **Legal**        **Default**                            **Required** **Variability**
+            **Range**
+  --------- ---------------  ------------------------------------- ------------- ---------------
+            *choices above*  derived from IZXFER characteristics        No           constant
+
+  -----------------------------------------------------------------
+
+
+
 **izZn1=*znName***
 
 Name of primary zone. Flow rates $>$ 0 are into the primary zone.

doc/src/records/report.md

@@ -94,6 +94,8 @@ Choice indicating report type. Report types may be described at greater length,
 
   DHWMTR  DHW meter report.  Requires *rpDHWMeter*
 
+  AFMTR   Air flow meter report.  Requires *rpAFMeter*
+
 <% if inactive_CNE_records %>
   AH      Air handler report. Requires *rpAh*.
 
@@ -202,6 +204,15 @@ Specifies DHW meter(s) to be reported, for *rpType*=DHWMTR.
 --------- ------------------------------ ------------- ---------------------------- ---------------
           name of a *DHWMETER*, ALL, SUM               Required for *rpType*=DHWMTR constant
 
+**rpAFMeter=*afMtrName***
+
+Specifies air flow meter(s) to be reported, for *rpType*=AFMTR.
+
+**Units** **Legal Range**                **Default**   **Required**                 **Variability**
+--------- ------------------------------ ------------- ---------------------------- ---------------
+          name of a *DHWMETER*, ALL, SUM               Required for *rpType*=AFMTR  constant
+
+
 <% if inactive_CNE_records %>
 **rpAh=*ahName***
 

doc/src/records/zone.md

@@ -279,11 +279,22 @@ Number of stories in zone, used in ELA model.
   ----------- ----------------------- ------------- -------------- -----------------
               1 $\leq$ *x* $\leq$ 3   1             No             constant
 
-**znWindFLkg=*floatTODO***
+**znWindFLkg=*float***
+
+Wind speed modifier factor.  The weather file wind speed is multiplied by this factor to yield a local wind speed for use in infiltration and convection models.
+
+  **Units**   **Legal Range**   **Default**                           **Required**   **Variability**
+  ----------- ----------------- ------------------------------------ -------------- -----------------
+                  $\geq$ 0       derived from zn_eaveZ and infShld           No             constant
+
+**znAFMtr=*afMtrName***
+
+Name of AFMETER object, if any, to which zone AirNet air flows are recorded.  *ZnAFMtr* defines a pressure boundary for accounting purposes.  Multiple zones having the same AFMETER are treated as a single volume -- interzone flows within that volume are not recorded.  For example, to obtain "building total" flow data, a common AFMETER could be assigned to several conditioned zones but not to adjacent unconditioned zones such as attic spaces.
+
+  **Units**    **Legal Range**       **Default**      **Required**   **Variability**
+  ----------- --------------------- ---------------- -------------- -----------------
+              *name of an AFMETER*   *not recorded*   No             constant
 
-  **Units**   **Legal Range**   **Default**   **Required**   **Variability**
-  ----------- ----------------- ------------- -------------- -----------------
-                                1             No             constant
 
 ## ZONE Exhaust Fan
 

src/CGCOMP.CPP

@@ -232,10 +232,8 @@ static float fShield[ 5][ 2] =
 					//   within two house heights
 };
 
-#if 1	// insurance, 11-18-2014
 	if (Z <= 0.f)
 		return 0.f;
-#endif
 
 	float SC = fShield[ bracket( 1, shieldClass, 5)-1][ 1];
 	if (terrainClass <= 0)
@@ -339,17 +337,15 @@ void AFMTR::amt_Accum(
 													// ASSUMES interval members ordered like DTIVLCH choices
 	AFMTR_IVL* sIvl0 = amt_GetAFMTR_IVL(ivl + 1);	// source: next shorter interval
 
-	int options = 0;	// default: track average
-
-	if (ivl == C_IVLCH_Y)
-		options = 1;	// average by day for non-sum-of year values
-						//   handles diffs due to month length
+	int options =
+		ivl == C_IVLCH_Y ? 1	// average by day for non-sum-of year values
+								//   handles diffs due to month length
+		:                  0;	// default: track average
 	for (int iPN=0; iPN<2; iPN++)
 		dIvl0[ iPN].amt_Accum(sIvl0+iPN, firstFlg, lastFlg, options);
 
 	if (lastFlg)
-	{
-		AFMTR* pAMSum = AfMtrR.p + AfMtrR.n;
+	{	AFMTR* pAMSum = AfMtrR.p + AfMtrR.n;
 		AFMTR_IVL* dIvlSum0 = pAMSum->amt_GetAFMTR_IVL( ivl);
 		for (int iPN = 0; iPN < 2; iPN++)
 			dIvlSum0[ iPN].amt_Accum(dIvl0+iPN, ss == 1, 0);
@@ -1050,13 +1046,13 @@ x		}
 void IZXRAT::iz_SetupAfMtrs()
 {
 	// Air flow category
-	if (iz_afCat == 0)
-		iz_afCat = iz_AfCatDefault();
+	if (!IsSet(IZXRAT_AFCAT))
+		iz_afCat = iz_AfCatDefault();	// default category (may return -1)
 
 	// AFMTR ptrs: NULL if no meter specified -> no air flow accounting
 	//  one pointer for positive flows, one for negative
 	iz_pAfMtr1 = iz_pAfMtr2 = NULL;	// insurance
-	if (iz_afCat > 0)
+	if (iz_afCat >= 0)
 	{	// set up ptrs to AFMTR(s)
 		const ZNR* zp;
 		if (iz_zi1 > 0)
@@ -1067,9 +1063,10 @@ void IZXRAT::iz_SetupAfMtrs()
 		{	// interzone transfers recorded iff to a different meter
 			zp = ZrB.GetAt(iz_zi2);
 			AFMTR* pAM = AfMtrR.GetAtSafe(zp->i.zn_afMtri);
-			if (pAM == iz_pAfMtr1)
+			if (pAM == iz_pAfMtr1  && !iz_IsHERV())
 				iz_pAfMtr1 = NULL;		// same meter on both sides of IZ
 										//   don't record IZ within meter
+										//   EXCEPT for HERV
 			else
 				iz_pAfMtr2 = pAM;		// z2 meter specified and differs from z1
 		}
@@ -1082,24 +1079,18 @@ void IZXRAT::iz_SetupAfMtrs()
 AFCAT IZXRAT::iz_AfCatDefault() const
 {
 	AFCAT afCat;
-	if (iz_IsSysAir())
+	if (!iz_IsAirNet())
+		afCat = -1;		// track only airnet flows
+	else if (iz_IsSysAir())
 		afCat = C_AFCAT_HVAC;
 	else if (iz_IsDuctLk())
 		afCat = C_AFCAT_DUCTLK;
+	else if (iz_IsHERV())
+		afCat = iz_IsHERVIZ() ? C_AFCAT_FANIZ : C_AFCAT_FANEX;
 	else if (iz_IsExterior())
-	{	if (iz_IsFixedFlow())
-			afCat = C_AFCAT_FANEX;
-		else
-			afCat = C_AFCAT_INFILEX;
-	}
+		afCat = iz_IsFixedFlow() ? C_AFCAT_FANEX : C_AFCAT_INFILEX;
 	else
-	{	if (iz_IsFixedFlow())
-			afCat = C_AFCAT_FANIZ;
-		else if (iz_IsAirNet())
-			afCat = C_AFCAT_INFILIZ;
-		else
-			afCat = 0;
-	}
+		afCat = iz_IsFixedFlow() ? C_AFCAT_FANIZ : C_AFCAT_INFILIZ;
 
 	return afCat;
 
@@ -1536,7 +1527,7 @@ RC IZXRAT::iz_EndSubhr()			// end-of-subhour vent calcs
 	}
 
 	// air flow accounting
-	iz_amfNom // nominal flow, lbm/sec
+	iz_amfNom // incoming nominal flow, lbm/sec
 		= (1.f - fVent)*iz_ad[0].ad_mdotP + fVent * iz_ad[1].ad_mdotP;
 	if (iz_nvcntrl == C_IZNVTYCH_ANHORIZ)
 		iz_amfNom
@@ -1545,8 +1536,12 @@ RC IZXRAT::iz_EndSubhr()			// end-of-subhour vent calcs
 	{	if (iz_pAfMtr1)
 			iz_pAfMtr1->amt_AccumCat(iz_afCat, iz_amfNom);
 		if (iz_pAfMtr2)
-			// flow is opposite direction from z2 POV
-			iz_pAfMtr2->amt_AccumCat(iz_afCat, -iz_amfNom);
+		{	// flow is opposite direction from z2 POV
+			// HERV: iz_pAfMtr2 points to exhaust source zone (may be z1)
+			//       HERV same for vent / no vent (use iz_ad[ 0] w/o fVent)
+			iz_pAfMtr2->amt_AccumCat(iz_afCat, 
+					iz_IsHERV() ? -iz_ad[0].ad_mdotX : -iz_amfNom);
+		}
 	}
 
 	return RCOK;
@@ -1696,6 +1691,8 @@ RC AIRNET::an_Calc(			// airnet flow balance
 		for (zi=0; zi < an_nz; zi++)
 		{	// Net mass flow to each zone s/b 0
 			// Solution not converged if netAMF > max( ResAbs, totAMF*ResRel)
+			//  Using larger of the two tolerances means zones with small abs flow converge loosely.
+			//  This avoids extra iterations to converge zones that have minor impact.
 			if (fabs( rV[ zi]) > ResAbs && fabs( rV[ zi]) > ResRel*an_mdotAbs[ zi])
 			{	bConverge = FALSE;
 				break;		// this zone not balanced, no need to check further

src/CGRESULT.CPP

@@ -258,17 +258,17 @@ static COLDEF afMtrColdef[] =
 	{ "FanZ+",          0,    5, D, oAFMt0(amt_fanIz), CV1 },
 	{ "Duct+",          0,    5, D, oAFMt0(amt_ductLk), CV1 },
 	{ "HVAC+",          0,    5, D, oAFMt0(amt_hvac),   CV1 },
-	{ "Tot-",           0,    5, D, oAFMt1(amt_total),  CV1 },
-	{ "Unkn-",          0,    5, D, oAFMt1(amt_unknown),CV1 },
-	{ "InfX-",          0,    5, D, oAFMt1(amt_infilEx),CV1 },
-	{ "VntX-",          0,    5, D, oAFMt1(amt_ventEx), CV1 },
-	{ "FanX-",          0,    5, D, oAFMt1(amt_fanEx), CV1 },
-	{ "InfZ-",          0,    5, D, oAFMt1(amt_infilIz),CV1 },
-	{ "VntZ-",          0,    5, D, oAFMt1(amt_ventIz), CV1 },
-	{ "FanZ-",          0,    5, D, oAFMt1(amt_fanIz), CV1 },
-	{ "Duct-",          0,    5, D, oAFMt1(amt_ductLk), CV1 },
-	{ "HVAC-",          0,    5, D, oAFMt1(amt_hvac),   CV1 },
-	{ 0,                 0,    0, 0, 0,                  CV1 }
+	{ "Tot-",           0,    6, D, oAFMt1(amt_total),  CV1 },
+	{ "Unkn-",          0,    6, D, oAFMt1(amt_unknown),CV1 },
+	{ "InfX-",          0,    6, D, oAFMt1(amt_infilEx),CV1 },
+	{ "VntX-",          0,    6, D, oAFMt1(amt_ventEx), CV1 },
+	{ "FanX-",          0,    6, D, oAFMt1(amt_fanEx), CV1 },
+	{ "InfZ-",          0,    6, D, oAFMt1(amt_infilIz),CV1 },
+	{ "VntZ-",          0,    6, D, oAFMt1(amt_ventIz), CV1 },
+	{ "FanZ-",          0,    6, D, oAFMt1(amt_fanIz), CV1 },
+	{ "Duct-",          0,    6, D, oAFMt1(amt_ductLk), CV1 },
+	{ "HVAC-",          0,    6, D, oAFMt1(amt_hvac),   CV1 },
+	{ 0,                0,    0, 0, 0,                  CV1 }
 };
 #undef D
 #undef oAFMt0
@@ -552,19 +552,18 @@ o          vpRxFooter(dvrip);				// do the footer, below.  clears VR_NEEDFOOT.
 void FC vpRxports( 	// virtual print reports and exports of given frequency for current interval
 
 	IVLCH freq,  		// interval desired: C_IVLCH_Y, M, D, H, S.
-	// HS generated internally when H or S given. HS cannot be given by caller.
-	BOO auszOnly/*=FALSE*/ )	/* non-0 to do ONLY autosizing results reports (AHSIZE, TUSIZE).
-				   used after autosize when main sim will not be performed.
-				   Experiment 5-97 to fix oversight in original ausz implementation;
-				   possibly autosize results reports should always be (have been) done this way
-				     (always call after autosize, then exclude then when auszOnly FALSE). */
+						// HS generated internally when H or S given. HS cannot be given by caller.
+	BOO auszOnly/*=FALSE*/ )	// non-0 to do ONLY autosizing results reports (AHSIZE, TUSIZE).
+						// used after autosize when main sim will not be performed.
+						// Experiment 5-97 to fix oversight in original ausz implementation;
+						// possibly autosize results reports should always be (have been) done this way
+						// (always call after autosize, then exclude then when auszOnly FALSE). */
 {
-	SI i;
-	SI reHead = 0;					// set non-0 to print report title & col heads even if not 1st time
-	SI doFoot = 0;					// non-0 for report end: blank line, Yr summary, etc
+	int reHead = 0;					// set non-0 to print report title & col heads even if not 1st time
+	int doFoot = 0;					// non-0 for report end: blank line, Yr summary, etc
 	RXPORTINFO rxt;					// much info to pass to/amoung callees
 
-	memset( &rxt, 0, sizeof(rxt));					// default all info members to 0
+	memset( &rxt, 0, sizeof(rxt));			// default all info members to 0
 	rxt.fqr = rxt.fq = freq;  				// store args
 
 // init by frequency; each case breaks; stuff used by more than one report type
@@ -602,7 +601,6 @@ void FC vpRxports( 	// virtual print reports and exports of given frequency for
 
 	switch (rxt.fq)
 	{
-		/*lint -e616 cases fall thru */
 	case C_IVLCH_S:
 		rxt.xebS[0] = 'a' + (char)Top.iSubhr; 	// ZEB export subhour: leave "" if not subhourly
 	case C_IVLCH_H:
@@ -613,32 +611,28 @@ void FC vpRxports( 	// virtual print reports and exports of given frequency for
 		rxt.xebM = Top.tp_date.month;
 	case C_IVLCH_Y:
 		;
-	default: ;	    /*lint +e616 */
+	default: ;
 	}
 
 // loop over reports active for given frequency
 
 	for ( ; ; )						// repeats to do HS if rpfreq==H or S.
-	{
-		DVRI *dvrip /*=NULL*/;
-		RPTYCH rpTy;
-		SI vrh, isAll, isExport;
-
-		for (i = (&Top.dvriY)[rxt.fq-1];  i;  i = dvrip->nextNow)	// loop over DvriB records in list for interval
+	{	DVRI *dvrip /*=NULL*/;
+		for (int i = (&Top.dvriY)[rxt.fq-1];  i;  i = dvrip->nextNow)	// loop over DvriB records in list for interval
 		{
 			dvrip = DvriB.p + i;				// point Date-dependent Virtual Report Info record
-			rpTy = dvrip->rpTy;    				// fetch report type
-			vrh = dvrip->vrh;					// fetch output destination
-			isExport = dvrip->isExport;   			// true if export (not report)
-			isAll = dvrip->isAll;  				// true if zi or mtri or ... is TI_ALL
+			RPTYCH rpTy = dvrip->rpTy;    		// fetch report type
+			int vrh = dvrip->vrh;				// fetch output destination
+			int isExport = dvrip->isExport; 	// true if export (not report)
+			int isAll = dvrip->isAll;  			// true if zi or mtri or ... is TI_ALL
 			rxt.flags = (rxt.flags &~(4|2)) | (isExport ? 4 : 2);	// set export (4) or report (2) flag bit; clear prior.
 			rxt.flags = (rxt.flags &~(16|8))			// set name (16) & time (8) col flags r/xport
 				| ( isExport ? (16|8) 			// exports show BOTH name and the 4 export time columns
 					: (isAll ? 16 : 8) ); 		// all- reports show name, others rpts show time column
-			rxt.flags = (rxt.flags &~(64|32))			// include shutter frac * (64) and Mode (32) columns
+			rxt.flags = (rxt.flags &~(64|32))	// include shutter frac * (64) and Mode (32) columns
 				| ( rxt.fq >= C_IVLCH_S	  		// .. in _HS and _S reports
 				    && (dvrip->ownTi > 0 || isAll )   	// .. for a single zone or all zones
-				|| isExport 				// .. and in all exports (keep format constant)
+				|| isExport 					// .. and in all exports (keep format constant)
 					? (64|32) : 0 );			// (but data is blanked/0'd below in non-subhr lines)
 
 			// footer line: also on last day of day, month, or year report
@@ -836,8 +830,8 @@ o				vpRxFooter(dvrip);	    		// virtual print report or export footer, below. c
 
 		}  // for i=
 
-	/* if hourly or subhourly specified, repeat for hourly+subhourly: hourly+subhourly reports are in a separate list
-								     as there is only one .nextNow in DVRI. */
+	// if hourly or subhourly specified, repeat for hourly+subhourly
+	//   hourly+subhourly reports are in a separate list as there is only one .nextNow in DVRI.
 		if (rxt.fq==C_IVLCH_H)			// if caller said do hour hourly lines
 		{	rxt.fq = C_IVLCH_HS;		// do the hourly lines of the HS reports/exports too
 			reHead = 0;					// no header at hrly line of HS's: header happened at subHour 0.
@@ -1501,7 +1495,9 @@ void DVRI::dv_vpAfMtrRow(RXPORTINFO *rxt, TI afMtri /*=-1*/)
 	if (afMtri == TI_SUM)
 		afMtri = AfMtrR.n;					// handle "sum"
 	AFMTR* pM = AfMtrR.GetAt(afMtri);		// record
-	AFMTR_IVL* pIvl = pM->amt_GetAFMTR_IVL( rxt->fq);	// interval
+	AFMTR_IVL* pIvl = pM->amt_GetAFMTR_IVL( rxt->fqr);	// interval
+								// results substr offset from .Y: M, D, H, S follow .Y, no HS.
+								//  .fqr is H or S when .fq is HS for hourly+subhourly reports
 
 	vpRxRow(this, rxt, pIvl, rxt->col1, pM->name, &rxt->xebM, &rxt->xebD, &rxt->xebH, rxt->xebS);
 }		// dv_vpDHWMtrRow

src/CNCULT.CPP

@@ -1533,7 +1533,7 @@ CULT( "izZn1",       DAT,   IZXRAT_ZI1,   RQD, 0, VEOI,   TYREF, &ZiB,   0.f,
 CULT( "izZn2",       DAT,   IZXRAT_ZI2,   0,   0, VEOI,   TYREF, &ZiB,   0.f,                N,   N),
 CULT( "izHConst",    DAT,   IZXRAT_UA,	  0,   0, VHRLY,  TYFL,  0,      0.f,                N,   N),
 CULT( "izNVType",    DAT,   IZXRAT_NVCNTRL,0,  0, VEOI,   TYCH,  0,   C_IZNVTYCH_NONE,       N,   N),
-CULT( "izAFCat",     DAT,   IZXRAT_AFCAT,  0,  0, VEOI,   TYCH,  0,      0,                  N,   N),
+CULT( "izAFCat",     DAT,   IZXRAT_AFCAT,  0,  0, VEOI,   TYCH,  0,     -1,                  N,   N),
 CULT( "izALo",       DAT,   IZXRAT_A1,    0,   0, VHRLY,  TYFL,  0,      0.f,                N,   N),
 CULT( "izAHi",       DAT,   IZXRAT_A2,    0,   0, VHRLY,  TYFL,  0,      0.f,                N,   N),
 CULT( "izL1",        DAT,   IZXRAT_L1,    0,   0, VEOI,   TYFL,  0,      0.f,                N,   N),