Merge pull request #526 from cse-sim/convection

Generalized forced convection model

Author: chipbarnaby

doc/src/records/door.md

@@ -252,6 +252,23 @@ Interior convection coefficient adjustment factor.  When drInHcModel=INPUT, hc=d
   variability: "subhourly")
   %>
 
+**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:
+
+      hcFrc = hConvF * (drInHcFrcCoeffs[ 1] + drInHcFrcCoeffs[ 2] * ACH ^ drInHcFrcCoeffs[ 3])
+
+where hConvF is the convection adjustment factor (derived from elevation, see Top hConvMod) and ACH is the zone air change rate per hour from the prior simulation step (including heat pump water heater evaporator air flow).  This formulation is dangerously flexible, so caution is advised when selecting coefficient values.
+
+The default hcFrc value (used when drInHcFrCoeff is not provided) is hConvF * znHcFrcF * ACH ^ 0.8.
+
+<%= member_table(
+  units: "Btuh/ft^2^-^o^F",
+  legal_range: "",
+  default: "*inherited from parent surface*",
+  required: "No",
+  variability: "subhourly") %>
+
 **endDoor**
 
 Indicates the end of the door definition. Alternatively, the end of the door definition can be indicated by the declaration of another object or by END.

doc/src/records/surface.md

@@ -348,7 +348,7 @@ END
 
   **sfInHcMult=*float***
 
-  Interior convection coefficient adjustment factor.  When sfInHcModel=INPUT, hc=sfInHcMult.  For other sfInHcModel choices, the model-derived hc is multiplied by sfInHcMult.
+  Interior convection coefficient adjustment factor.  When sfInHcModel=INPUT, hc=sfInHcMult.  For other sfInHcModel choices, the model-derived hc is multiplied by sfInHcMult.  When sfInHcModel=UNIFIED, natural (buoyancy-driven) and forced convection coefficient values are combined according to TOP inHcCombinationMethod, then sfInHcMult is applied.
 
 <%= member_table(
   units: "",
@@ -357,6 +357,24 @@ END
   required: "No",
   variability: "subhourly") %>
 
+**sfInHcFrcCoeffs=*float array***
+
+Specifies 3 coefficients for an alternative inside surface forced convection model (applicable only for sfInHCModel=UNIFIED).  When given, the inside surface forced convection coefficient for this surface is derived as follows:
+
+      hcFrc = hConvF * (sfInHcFrcCoeffs[ 1] + scInHcFrcCoeffs[ 2] * ACH ^ sfInHcFrcCoeffs[ 3])
+
+where hConvF is the convection adjustment factor (derived from elevation, see Top hConvMod) and ACH is the zone air change rate per hour from the prior simulation step (including heat pump water heater evaporator air flow).  This formulation is dangerously flexible, so caution is advised when selecting coefficient values.
+
+The default hcFrc value (used when sfInHcFrCoeff is not provided) is hConvF * znHcFrcF * ACH ^ 0.8.
+
+<%= member_table(
+  units: "Btuh/ft^2^-^o^F",
+  legal_range: "",
+  default: "*see above*",
+  required: "No",
+  variability: "subhourly") %>
+
+
 The items below give values associated with CSE's model for below grade surfaces (sfExCnd=GROUND).  See CSE Engineering Documentation for technical details.
 
 **sfFnd=*fdName***

doc/src/records/top-members.md

@@ -688,6 +688,27 @@ $$0.24 + 0.76 \cdot P_{Location}/P_{SeaLevel}$$
   required: "No",
   variability: "constant") %>
 
+**inHcCombinationMethod=*choice***
+
+Selects the method for combining inside face (zone-facing) forced and natural (buoyancy-driven) convection coefficients for surfaces using the UNIFIED convection model.  This is a development aid not typically used in production runs.
+
+<%= csv_table(<<END, :row_header => true)
+Method,	   hcComb
+SUM,        hcNat + hcFrc
+QUADRATURE, sqrt(hcNat^2 + hcFrc^2)
+WEIGHTED,   hcNat when ACH<0.5
+ ,           hcFrc when ACH>3.0
+ ,           else weighted combination
+END
+%>
+
+<%= member_table(
+  units: "",
+  legal_range: "*choices above*",
+  default: "SUM",
+  required: "No",
+  variability: "constant") %>
+
 **soilDiff=*float***
 
 *Note: soilDiff is used as part of the simple ground model, which is no longer supported. Use soilCond, soilSpHt, and SoilDens instead.*

doc/src/records/window.md

@@ -184,7 +184,7 @@ END
 
 **wnExHcModel=*choice***
 
-Selects the model used for exterior surface convection when wnModel = Forward\_Difference.
+Selects the model used for exterior surface convection.
 
 <%= member_table(
   units: "",
@@ -242,6 +242,23 @@ Interior convection coefficient adjustment factor.  When wnInHcModel=INPUT, hc=w
   variability: "subhourly")
   %>
 
+**wnInHcFrcCoeffs=*float array***
+
+Specifies 3 coefficients for an alternative inside surface forced convection model (applicable only for wnInHCModel=UNIFIED).  When given, the inside surface forced convection coefficient for this surface is derived as follows:
+
+      hcFrc = hConvF * (wnInHcFrcCoeffs[ 1] + wnInHcFrcCoeffs[ 2] * ACH ^ wnInHcFrcCoeffs[ 3])
+
+where hConvF is the convection adjustment factor (derived from elevation, see Top hConvMod) and ACH is the zone air change rate per hour from the prior simulation step (including heat pump water heater evaporator air flow).  This formulation is dangerously flexible, so caution is advised when selecting coefficient values.
+
+The default hcFrc value (used when wnInHcFrCoeff is not provided) is hConvF * znHcFrcF * ACH ^ 0.8.
+
+<%= member_table(
+  units: "Btuh/ft^2^-^o^F",
+  legal_range: "",
+  default: "*inherited from parent surface*",
+  required: "No",
+  variability: "subhourly") %>
+
 **wnSHGC=*float***
 
 Rated Solar Heat Gain Coefficient (SHGC) for the window assembly.

doc/src/records/zone.md

@@ -133,7 +133,7 @@ Zone air exchange rate used in determination of interior surface convective coef
 
 **znHcFrcF=*float***
 
-Zone surface forced convection factor.  Interior surface convective transfer is modeled as a combination of forced and natural convection.  hcFrc = znHcFrcF * znHcAirX^.8.  See CSE Engineering Documentation.
+Zone surface forced convection factor.  Default interior surface convective transfer is modeled as a combination of forced and natural convection.  hcFrc = znHcFrcF * ACH^.8, where ACH = znHcAirX + heat pump water heater evaporator air exchange rate  See CSE Engineering Documentation.
 
 <%= member_table(
   units: "Btuh/ft^2^-^o^F",

src/CNDTYPES.DEF

@@ -337,6 +337,11 @@ PIPESEGP -- "class PIPESEG*"
 			  DOE2 "DOE2"
 			  UNIFIED "Unified"
 			  }
+*choicb HCCOMBMETH {
+			 SUM "Sum"
+			 WEIGHTED "Weighted"
+			 QUADRATURE "Quadrature"
+			 }
 *choicb RSYSTY {
 			ACFURN "ACFurnace"
 			ACPMFURN "ACPMFurnace"

src/CNFIELDS.DEF

@@ -162,7 +162,8 @@ GROUNDMODELCH GROUNDMODELCH LMNONE   UNNONE
 FBXREFCH      FBXREFCH     LMNONE   UNNONE
 FBZREFCH      FBZREFCH     LMNONE   UNNONE
 CONVMODELCH	  CONVMODELCH  LMNONE    UNNONE
-RSYSTY	  RSYSTY	   LMNONE	 UNNONE
+HCCOMBMETH    HCCOMBMETH   LMNONE   UNNONE
+RSYSTY	      RSYSTY	   LMNONE	 UNNONE
 RSYSOAVTYCH	  RSYSOAVTYCH  LMNONE	 UNNONE
 RSYSDEFROSTMODELCH	  RSYSDEFROSTMODELCH  LMNONE	 UNNONE
 AUXHEATTY	  AUXHEATTY    LMNONE	 UNNONE

src/CNRECS.DEF

@@ -283,8 +283,6 @@ RECORD TOPRAT "top" *RAT	/* top level RAT: contains control info and all once-on
 							//       determined by zone that wants the least vent
 							//  or -1 for zonal vent control
 
-    *r NOYESCH tp_hConvMod	// enable/disable convection convective coefficient pressure modification factor (tp_hConvF below)
-							//   mostly for debugging.
     *f SI verbose 			// screen messages: autosizing: 0 none, 1 some (dflt?), 2-5 more
 							//   -1: suppress progress messages ("Input", "Warmup", etc.) via setScreenQuiet()
     *h INT tp_dbgPrintMask	// debug print mask, controls DbPrintf() etc., schedulable via std capabilities
@@ -381,11 +379,17 @@ RECORD TOPRAT "top" *RAT	/* top level RAT: contains control info and all once-on
 							//   airRhoK*tp_airSH  dfl ~9.535  NEEDS UNITS
     *r float airXK			// divide by abs temp for specific heat of flow (Btuh/cfm-F)
 							//   airVshK, times 60 to match time units. dfl ~572.1
+    *r NOYESCH tp_hConvMod	// enable/disable convection convective coefficient pressure modification factor (tp_hConvF below)
+							//   mostly for debugging.
 	*r float tp_hConvF		// convective coefficient pressure modification factor
 							//   =(.24 + .76*PresAtm/PresAtmSeaLevel)
-							//   used in some surface transfer models, reduces convection as function of elevation
+							//   reduces convective coefficients as function of elevation
+                            //   in some convection modelsPresAtmSeaLevel
 							//   source = ASHRAE 1199-RP Barnaby et al. 2004
-    // and: enthalpy/lb is airSh * absTemp + 1061 * w.  (Btu/lb)
+                            // and: enthalpy/lb is airSh * absTemp + 1061 * w.  (Btu/lb)
+    *r HCCOMBMETH tp_inHcCombMeth // method used to combine inside surface hcNat and hcFrc
+                              //    see SBC::sb_CombineInHcNatFrc()
+
 
     // air property uses:
     *declare "float airDens( float t) { return airRhoK / ( t + 459.67f); }	// air density for temp  lb/ft3"
@@ -1091,6 +1095,7 @@ RECORD SBCBASE "SBCBASE" *SUBSTRUCT *HIDEALL
   *r DBL sb_fSky		//   "view factor" to radiant surround at sky temp
   *r DBL sb_fAir		//   "view factor" to radiant surround at air temp (ground, horizon)
 
+
   *s *e FLOAT_GEZ sb_hcNat	// surface natural convection coefficient, Btuh/ft2-F
   *s *e FLOAT_GEZ sb_hcFrc	// surface forced (wind) convection coefficient, Btuh/ft2-F
   *s *e FLOAT_GEZ sb_hcMult	// surface convection coefficient multiplier, dimless
@@ -1156,21 +1161,22 @@ RECORD SBC "SBC" *SUBSTRUCT *BASECLASS SBCBASE		// surface boundary condition su
   *declare "virtual int sb_Class() const;"
   *declare "void sb_CalcAwAbsSlr();"
   *declare "virtual const char* sb_ParentName() const;"
-  *declare "int sb_HasHcNat() const;"
+  *declare "bool sb_HasHcNat() const;"
+  *declare "bool sb_IsSet( int fnSBC) const;"
   *declare "void sb_SetRunConstants( int dbPrint);"
   *declare "void sb_SetCoeffs( double area, double uC);"
   *declare "void sb_HCAmbient();"
   *declare "float sb_CGrnd() const;"
   *declare "void sb_SetCoeffsWallBG( float a[]);"
   *declare "void sb_SetCoeffsFloorBG( float a4, float a5);"
   *declare "void sb_HCZone();"
+  *declare "float sb_CombineInHcNatFrc() const;"
   *declare "void sb_SetTx();"
   *declare "double sb_QHT() const { return sb_qrAbs + sb_hxa*sb_txa + sb_hxr*sb_txr; }"
   *declare "void sb_BalCheck();"
   *declare "const char* sb_SideText();"
   *declare "static void sb_DbPrintf( const char* tag, const SBC& sbcO, const SBC& sbcI);"
 
-
   *r XSURFP sb_pXS		// parent pointer
   *r int sb_si			// side of *sb_pXS represented by this SBC
 						//   0=inside, 1=outside
@@ -1197,6 +1203,11 @@ RECORD SBC "SBC" *SUBSTRUCT *BASECLASS SBCBASE		// surface boundary condition su
   *r DBL sb_cosAtv		// cos( angle to vertical) 0 - 1 (never < 0)
   *i CONVMODELCH sb_hcModel // surface convective coefficient model
 						//       specifies calc method sb_hcNat and sb_hcFrc
+  *declare "enum { sbhcUSECOEFFS=0x1 };"
+  *r SI sb_hcFrcOptions // options re inside forced convection model
+                        //   1: use sb_hcFrcCoeffs (see code), else zn_hcFrc
+  *r *array DIM_HCFRCCOEFFS FLOAT sb_hcFrcCoeffs // coefficients for forced convection model (inside only)
+                                                 // 1 extra array member required by cul
   *r FLOAT sb_hcLChar	// characteristic length, ft
 						//   used in derivation of exterior forced convective coeff
 						//   default = 10 ft
@@ -1388,6 +1399,8 @@ RECORD SFI "surface" *RAT	// opaque surface / door / window input info RAT
 	*declare "RC sf_CkfSURFGround( int options);"
 	*declare "RC sf_CkfDOOR( int options);"
 	*declare "RC sf_CkfWINDOW( int options);"
+    *declare "RC sf_CkfInsideConvection();"
+    *declare "RC sf_SBCConvectionInheritIf( const SFI* pSfParent, int si);"
 	*declare "RC sf_TopSf2();"
 	*declare "RC sf_MakMs();"
 	*declare "RC sf_SetupKiva();"
@@ -2671,10 +2684,12 @@ RECORD ZNR "zone" *RAT	// zone runtime info RAT.  Set mainly from separate ZNI
 	*s *e FLOAT zn_airX		// overall zone air change rate (changes/hr)
 							//   includes *all* air flows; used re convective coeff determination
 
-	// *s *e FLOAT i.zn_hcAirX	// zn_airX + add'l 4.8 ACH for non-air zones having HVAC loads
+	// *s *e FLOAT i.zn_hcAirX	// zn_airX + add'l 4.8 ACH for non-air zones having HVAC loads, changes/hr
 								//   inputable for testing; used re convection coeff model
-	*s FLOAT zn_hcAirXls	// prior subhour value of i.zn_hcAirX
-	*s FLOAT zn_hcFrc		// inside surface forced convection coefficient, Btuh/ft2-F
+	*s FLOAT zn_hcAirXls	// prior subhour value of i.zn_hcAirX, change/hr
+    *s *e FLOAT zn_hcAirXComb   // combined zone air change rate for this subhour, changes/hr
+                                //  = zn_hcAirXls + zn_hpwhAirX
+	*s *e FLOAT zn_hcFrc		// inside surface forced convection coefficient, Btuh/ft2-F
 	*s FLOAT zn_windPresV	// wind velocity pressure, lbf/ft2
 							//     zone-specific per zn_EaveZ and zn_infShield
 

src/ancrec.cpp

@@ -58,25 +58,19 @@ record::record(BP _b, TI i, SI noZ/*=0*/)  	// construct record i of basAnc b, z
 	r_status = 1; 		// say space in use and record good
 }			// record::record
 //---------------------------------------------------------------------------------------------------------------------------
-void* record::field( int fn) 				// point to member in record by FIELD #
-{	return (void *)((char *)this + b->fir[fn].fi_off);  }
-//-----------------------------------------------------------------------------
-const void* record::field( int fn) const
-{	return (const void *)((const char *)this + b->fir[fn].fi_off);  }
-//-----------------------------------------------------------------------------
 void record::RRFldCopy(		// record-to-record field copy
-	const record* r,	// source record (same type as this)
+	const record* rSrc,	// source record (same type as this)
 	int fn)				// field #
 // handles NaNs re expressions
 {
 #if defined( _DEBUG)
-	if (b->rt != r->b->rt)
+	if (b->rt != rSrc->b->rt)
 		err( PWRN, "%s:%s RRFldCopy: RT mismatch", b->what, Name());
 #endif
 	int dt = DType( fn);
 	int sz = GetDttab( dt).size;
-	memcpy( field( fn), r->field( fn), sz);
-	fStat( fn) = r->fStat( fn);
+	memcpy( field( fn), rSrc->field( fn), sz);
+	fStat( fn) = rSrc->fStat( fn);
 }	// record::RRFldCopy
 //-----------------------------------------------------------------------------
 void record::FldCopy(		// field-to-field copy (within record)
@@ -749,8 +743,8 @@ RC record::ArrayCheck(		// check array input for expected count
 					msg = strtprintf("%d to %d", nSetExpectedMin, nSetExpectedMax);
 			}
 			if (msg)
-				rc |= oer("%d values found for array '%s' (expected %s)",
-					nSet, mbrIdTx(fn), msg);
+				rc |= oer("%d value%s found for array '%s' (expected %s)",
+					nSet, nSet==1 ? "" : "s", mbrIdTx(fn), msg);
 		}
 	}
 	return rc;

src/ancrec.h

@@ -182,15 +182,19 @@ class record		// base class for records
     record() {}					// cannot construct record without basAnc and subscript
   public:
 	const char* Name() const { return name.CStr();  }
-    void* field( int fn); 				// point to member in record by FIELD #
-	const void* field( int fn) const;
+	void* field( int fn) 				// point to member in record by FIELD #
+	{	return (void *)((char *)this + b->fir[fn].fi_off);  }
+	const void* field( int fn) const
+	{	return (const void *)((const char *)this + b->fir[fn].fi_off);  }
+	const char* mbrName(int fn) const {	return b->fir[fn].fi_mName; }
+
 	int DType(int fn) const;
 
-	void RRFldCopy( const record* r, int fn);
-	int RRFldCopyIf( const record* r, int fn)
+	void RRFldCopy( const record* rSrc, int fn);
+	int RRFldCopyIf( const record* rSrc, int fn)
 	{	int ret = !IsSet( fn);
 		if (ret)
-			RRFldCopy( r, fn);
+			RRFldCopy( rSrc, fn);
 		return ret;
 	}
 	void FldCopy( int fnS, int fnD);