Kiva modeling enhancements (breaking change)

doc/src/records/fndblock.md

@@ -1,20 +1,28 @@
 # FNDBLOCK
 
-Foundation blocks are materials within the two-dimensional domain beyond those defined by the slab and wall SURFACEs. Each block is represented as a rectangle in the domain by specifying the X (lateral) and Z (vertical) coordinates of two opposite corners. The coordinate system for each point is relative to the X and Z references defined by the user. As a convention The positive X direction is away from the building, and the positive Z direction is down.
+Foundation blocks are materials within the two-dimensional domain beyond those defined by TOP soil properties, the parent FOUNDATION object, and floor and wall SURFACEs. Common examples of using FNDBLOCKs include representing:
 
-Options for X and Z references are illustrated in the figure below.
+- Perimeter slab insulation
+- Slab gap insulation
+- Partial interior wall insulation
+- Exterior horizontal or vertical insulation
+- Concrete footings
 
-![Foundation block references](media/fd_refs.png)
+Each block is represented as a rectangle in the domain by specifying the X (lateral) and Z (vertical) coordinates of two opposite corners. It does not matter which of the four corners of a block are used to define the two points as long as they are opposite corners. The coordinate system for each point is relative to the X and Z references defined by the user. By convention, the positive X direction is away from the building, and the positive Z direction is down. FNDBLOCKs that overlap materials defined by TOP, FOUNDATION, SURFACE objects, or previously defined FNDBLOCKs will override the thermal properties within the extents of the FNDBLOCK.
 
-The default reference is WALLINT, WALLTOP.
+Each corner point of a FNDBLOCK is defined relative to its reference point. The user may specify reference points to simplify the calculation of corner point coordinates. X and Z point values of zero imply that a point is the same as the reference point. The default for X and Z point values is zero since points will often align with one or both of the reference values. Options for X and Z references are illustrated in the figure below.
 
-An example of defining a block for interior wall insulation is shown below. Here the two points defining the block (P1 and P2) are both shown relative to their reference points (Ref1 and Ref2, respectively).
+![Foundation block reference choices](media/fd_refs.png)
 
-![Foundation block example](media/fd_block.png)
+The default X and Z references for the first corner point is WALLINT and WALLTOP, respectively. The second set of references default to the same reference as the first point.
 
-Note: X and Z point values of zero imply that a point is the same as the reference point. The default for X and Z point values is zero since points will often align with one or both of the reference values.
+An example of defining FNDBLOCKs for a basement are shown below.
 
-It does not matter which of the four corners of a block are used to define the two points as long as they are opposite corners.
+![Foundation block example for a basement with partial wall insulation](media/fd_block_basement.png)
+
+The example for a slab foundation shown below illustrates how leveraging default values can simplify user input.
+
+![Foundation block example for a slab with gap and inerior perimeter insulation](media/fd_block_slab.png)
 
 **fbMat=*matName***
 
@@ -96,7 +104,7 @@ Relative X origin for *fbX2* point. Options are:
 <%= member_table(
   units: "",
   legal_range: "*choices above*",
-  default: "WALLINT",
+  default: "same as *fbX1Ref*",
   required: "No",
   variability: "constant") %>
 
@@ -114,7 +122,7 @@ Relative Z origin for *fbZ2* point. Options are:
 <%= member_table(
   units: "",
   legal_range: "*choices above*",
-  default: "WALLTOP",
+  default: "same as *fbZ1Ref*",
   required: "No",
   variability: "constant") %>
 

doc/src/records/foundation.md

@@ -1,16 +1,16 @@
 # FOUNDATION
 
-Foundation describes the two-dimensional relationship between ground-contact SURFACEs (i.e., **sfExCnd** = GROUND) and the surrounding ground. A FOUNDATION is referenced by Floor SURFACEs (see **sfFnd**). FOUNDATIONs are used to describe the two-dimensional features of foundation designs that cannot be captured by the typical one-dimensional constructions. Dimensions from the one-dimensional CONSTRUCTIONs associated with ground-contact floors and walls will automatically be interpreted into the two-dimensional context.
+Foundation describes the two-dimensional relationship between ground-contact SURFACEs (i.e., **sfExCnd** = GROUND) and the surrounding ground. A FOUNDATION is referenced by ground-contact floor SURFACEs (see **sfFnd**). FOUNDATIONs are used to describe the two-dimensional features of foundation designs that cannot be captured by the typical one-dimensional CONSTRUCTIONs. The dimensions from the one-dimensional CONSTRUCTIONs associated with ground-contact floors and walls are automatically interpreted into the two-dimensional context.
 
-![Two-dimensional context](media/fd_context.png)
+![Two-dimensional context for a slab foundation](media/fd_context_slab.png)
 
-Any wall SURFACEs in contact with the ground must refer to a Floor SURFACE object (see **sfFndFloor**) to indicate which floor shares the same ground domain as a boundary condition (and establish the two-dimensional context for the basis of the ground calculations).
+![Two-dimensional context with below grade walls](media/fd_context_basement.png)
 
-FOUNDATION objects are used to instantiate instances of heat transfer within Kiva.
+Any ground-contact wall SURFACEs in contact with the ground must refer to a Floor SURFACE object (see **sfFndFloor**) to indicate which floor shares the same ground boundary condition in the two-dimensional context.
 
 MATERIALs used in a FOUNDATION cannot have variable properties at this time.
 
-Most of the relevant dimensions and properties in the two-dimensional context are defined in the FOUNDATION object (and FNDBLOCK subobjects) with a few exceptions specified by specific SURFACEs:
+Some of the relevant dimensions and properties in the two-dimensional context are defined in the FOUNDATION object (and FNDBLOCK subobjects), but several others are specified by the corresponding SURFACE objects:
 
 - sfFnd
 - sfFndFloor
@@ -34,11 +34,9 @@ Some properties applying to all FOUNDATIONs are defined at the TOP level:
 - grndMaxGrthCoeff
 - grndTimeStep
 
-The following data members describe the dimensions and properties of the foundation wall. For below-grade walls, the CONSTRUCTION (and corresponding width) of the foundation wall is defined by the Wall SURFACEs referencing the FOUNDATION object. For on-grade floors, the CONSTRUCTION of the foundation wall must be defined using **fdFtCon**. The actual height of the foundation wall (from the top of the wall to the top of the slab) is defined by the corresponding SURFACE objects.
+The following data members describe the dimensions and properties of the structural foundation wall. The height of the foundation wall (from the top of the wall to the top of the slab) is defined by **sfHeight** in wall SURFACEs that specify the same **sfFndFloor** that references the FOUNDATION (through **sfFnd**).
 
-![Foundation wall dimensions](media/fd_dims.png)
-
- Other components of the foundation design (e.g., interior/exterior insulation) as well as other variations in thermal properties within the ground are defined using FNDBLOCK (foundation block) objects. Any number of FNDBLOCKs can appear after the definition of a FOUNDATION to be properly associated.
+Other components of the foundation design (e.g., interior/exterior insulation) as well as other variations in thermal properties within the ground are defined using FNDBLOCK (foundation block) objects. Any number of FNDBLOCKs can appear after the definition of a FOUNDATION to be properly associated.
 
 **fdName**
 
@@ -52,19 +50,18 @@ Name of foundation; give after the word FOUNDATION. Required for reference from
 
 **fdWlHtAbvGrd=*float***
 
-Wall height above grade.
+Distance between the grade level and the top of the foundation wall.
 
 <%= member_table(
   units: "ft",
   legal_range: "x $\\geq$ 0",
-  default: "0.0",
+  default: "0.5",
   required: "No",
   variability: "constant") %>
 
 **fdWlDpBlwSlb=*float***
 
-<!-- TODO: Optionally below grade? -->
-Wall depth below slab.
+Distance between the bottom of the slab and the bottom of the foundation wall. Foundation walls typically extend to the bottom of the slab and rest on a footing. If the footing isn't explicitly modeled as a FNDBLOCK, this value can be extended to approximate the footing.
 
 <%= member_table(
   units: "ft",
@@ -73,14 +70,14 @@ Wall depth below slab.
   required: "No",
   variability: "constant") %>
 
-**fdFtCon=*conName***
+**fdWlCon=*conName***
 
-Name of CONSTRUCTION of the footing wall. Only required **IF** it is a slab foundation (i.e., no wall surfaces reference this FOUNDATION object).
+Name of the CONSTRUCTION for the structural foundation wall. In the two-dimensional context, this construction spans from the top of the foundation wall to its depth below the slab (*fdWlDpBlwSlb*). Any construction on the interior of the wall (spanning from the top of the foundation wall to the top of the slab), must be defined by the *sfCon* of the corresponding wall surface. Typically, this CONSTRUCTION will be a single layer of poured concrete.
 
 <%= member_table(
   legal_range: "Name of a *Construction*",
   default: "*none*",
-  required: "if a slab foundation",
+  required: "Yes",
   variability: "constant") %>
 
 **endFoundation**

doc/src/records/surface.md

@@ -104,7 +104,7 @@ Surface U-value (NOT including surface (air film) conductances). For surfaces fo
   units: "Btuh/ft^2^-^o^F",
   legal_range: "*x* $>$ 0",
   default: "Determined from *sfCon*",
-  required: "if *sfCon* not given",
+  required: "if *sfCon* not given and if *sfExCnd* is not GROUND",
   variability: "constant") %>
 
 **sfCon=*conName***
@@ -115,9 +115,14 @@ Name of CONSTRUCTION of the surface.
   units: "",
   legal_range: "Name of a *CONSTRUCTION*",
   default: "*none*",
-  required: "unless *sfU* given",
+  required: "if *sfU* not given and if *sfExCnd* is not GROUND",
   variability: "constant") %>
 
+Note: When *sfExCnd* is GROUND, *sfCon* may be omitted to indicate:
+
+- exposed earth (when *sfType* is FLOOR), or
+- bare foundation wall (when *sfType* is WALL) -- the foundation wall 
+
 **sfLThkF=*float***
 
 Sublayer thickness adjustment factor for FORWARD\_DIFFERENCE conduction model used with sfCon surfaces.  Material layers in the construction are divided into sublayers as needed for numerical stability.  sfLThkF allows adjustment of the thickness criterion used for subdivision.  A value of 0 prevents subdivision; the default value (0.5) uses layers with conservative thickness equal to half of an estimated safe value.  Fewer (thicker) sublayers improves runtime at the expense of accurate representation of rapid changes.
@@ -471,9 +476,9 @@ The following tables summarize the defaults and legal ranges of surface members
   ----------- ------------------------------------------------------------
   sfArea      **required**
 
-  sfCon       **required unless sfU given**
+  sfCon       **required unless sfU given, or if *sfExCnd* = GROUND**
 
-  sfU         **required unless sfCon given**
+  sfU         **required unless sfCon given, or if *sfExCnd* = GROUND**
 
   sfInH       optional, default = 1.5
 

src/CMakeLists.txt

@@ -278,6 +278,11 @@ source_group("Def Files" FILES ${defs})
 
 target_link_libraries(CSE PRIVATE ${libs})
 
+if(KIVA_GROUND_PLOT)
+  set_source_files_properties(foundation.cpp foundation.h PROPERTIES COMPILE_DEFINITIONS GROUND_PLOT)
+  target_link_libraries(CSE PUBLIC groundplot)
+endif()
+
 add_dependencies(CSE version_header)
 
 if (${CSE_COMPILER_NAME} STREQUAL "msvc" AND ${CSE_BUILD_ARCHITECTURE} STREQUAL "32")

src/CNRECS.DEF

@@ -1574,27 +1574,6 @@ RECORD MSRAT "mass" *RAT 	// Masses run rat
 
 *END			// MSRAT
 
-//=======================================================================================================
-RECORD KIVA "kiva" *RAT 	// Kiva instance run rat
-	*prefix kv_
-	*exdes				// d'tor
-	*declare "ZNR* kv_GetZone() const;"
-	*declare "RC kv_Create();"
-	*declare "RC kv_RddInit();"
-	*declare "RC kv_SetInitBCs(DOY jDay);"
-	*declare "RC kv_SetBCs();"
-	*declare "RC kv_Step(float dur);"
-
-	*declare "class Kiva::Instance* kv_instance;"
-	*declare "std::vector<TI> kv_walls;"
-
-	*r TI kv_floor				// floor reference
-	// list of wall references
-	*r FRAC_GZ kv_perimWeight	// weight of this kiva instance for results of corresponding floor
-
-*END			// KIVA
-
-
 //=============================================================================
 RECORD SGI "sgdist" *RAT		// solar gain distribution info during input
 
@@ -1721,9 +1700,7 @@ RECORD FOUNDATION "foundation" *RAT	// foundation input info
  //input
  *i LEN fd_wlHtAbvGrd		// Height of foundation wall above grade
  *i LEN fd_wlDpBlwSlb		// Depth of foundation wall below the slab
- *i TI fd_ftWlConi			// Foundation wall construction (CON subscript) RQD if
-							// no walls associated with this foundaiton
-							// (i.e., it is a slab)
+ *i TI fd_wlConi			// Foundation wall construction (CON subscript)
 
 *END		// FND
 
@@ -1737,8 +1714,8 @@ RECORD FNDBLOCK "foundationBlock" *RAT	// foundation component input info
  *i FBZREFCH fb_z1Ref		// Point 1 Z reference
  *i FLOAT fb_x1				// Point 1 X value (relative to reference)
  *i FLOAT fb_z1				// Point 1 X value (relative to reference)
- *i FBXREFCH fb_x2Ref		// Point 2 X reference
- *i FBZREFCH fb_z2Ref		// Point 2 Z reference
+ *i FBXREFCH fb_x2Ref		// Point 2 X reference (defaults to Point 1 X reference)
+ *i FBZREFCH fb_z2Ref		// Point 2 Z reference (defaults to Point 1 Z reference)
  *i FLOAT fb_x2				// Point 2 X value (relative to reference)
  *i FLOAT fb_z2				// Point 2 X value (relative to reference)
 
@@ -3995,6 +3972,8 @@ RECORD AFMTR "AFMETER" *RAT 	// Airflow meter
 
 
  // results: average cfm std air
+ //     0 = airflow in (+)
+ //     1 = airflow out (-)
  //     for each interval (member here), usage by end use (substruct member):
  // CAUTION: ordered for subscripting by IVLCH-1.
     *y *e *array 2 *nest AFMTR_IVL Y   	// run (aka year or annual)
@@ -5635,7 +5614,7 @@ RECORD MTR "meter" *RAT 	// Meter input/runtime: energy use by meter, interval,
 
 
  // inputs: rates
-    *i float rate			// cost per Btu of use
+    *h float rate			// cost per Btu of use
     *i float dmdRate		// dmdCost per Btu of demand, for a month
     *r *array DIM_SUBMETERLIST TI mtr_subMtri;     // submeters
     *h *array DIM_SUBMETERLIST FLOAT mtr_subMtrMult   // submeter multipliers

src/cncult.cpp

@@ -184,8 +184,23 @@ static CULT conT[] = //--------------------------------- CONSTRUCTION Cmd table
 RC FC fbStarCkf([[maybe_unused]] CULT *c, /* GT* */ [[maybe_unused]] void *p, [[maybe_unused]] void *p2, [[maybe_unused]] void *p3) /*ARGSUSED*/
 {
 	RC rc = RCOK;
-
-
+	FNDBLOCK* pFndBlock = (FNDBLOCK *)p;
+	// Smart defaults for second reference points
+	if (pFndBlock->IsSet(FNDBLOCK_X1REF))
+	{
+		if (!pFndBlock->IsSet(FNDBLOCK_X2REF))
+		{
+			pFndBlock->fb_x2Ref = pFndBlock->fb_x1Ref;
+		}
+	}
+	if (pFndBlock->IsSet(FNDBLOCK_Z1REF))
+	{
+		if (!pFndBlock->IsSet(FNDBLOCK_Z2REF))
+		{
+			pFndBlock->fb_z2Ref = pFndBlock->fb_z1Ref;
+		}
+	}
+
 	return rc;
 #undef P
 }		// fcStarCkf
@@ -226,9 +241,9 @@ static CULT fdT[] = //---------------------------------- FOUNDATION Cmd Table
 	// id            cs    fn         f     uc evf   ty     b        dfls    p2 ckf
 	//-------------  ----- ---------  ----  -- ----- ------ -------  ------  -- ----
 	CULT("*",	           STAR,  0,         0,    0, 0,    0,     0,       N,      0.f,  N, fdStarCkf),
-	CULT("fdWlHtAbvGrd",   DAT,   FOUNDATION_WLHTABVGRD,    0,    0, VEOI, TYFL,  0,       0.f,     N,   N),
+	CULT("fdWlHtAbvGrd",   DAT,   FOUNDATION_WLHTABVGRD,    0,    0, VEOI, TYFL,  0,       0.5f,     N,   N),
 	CULT("fdWlDpBlwSlb",   DAT,   FOUNDATION_WLDPBLWSLB,    0,    0, VEOI, TYFL,  0,       0.f,     N,   N),
-	CULT("fdFtCon",        DAT,   FOUNDATION_FTWLCONI,  0,  0, VEOI, TYREF, &ConiB,  N,      0.f,  N, N),
+	CULT("fdWlCon",        DAT,   FOUNDATION_WLCONI,  RQD,  0, VEOI, TYREF, &ConiB,  N,      0.f,  N, N),
 	CULT("fndblock",     RATE, 0,                 0,            0, 0,      0,      &FbiB, 0.f,        fbT,   N),
 	CULT("endFoundation",  ENDER, 0,     0,    0, 0, 0,     0,       N, 0.f,  N,   N),
 	CULT()
@@ -675,7 +690,7 @@ RC SFI::sf_CkfSURF(		// surface checker
 // sf_CkfSURF: check surface model for consistency with other parameters
 	BOO consSet = IsSet( SFI_SFCON );
 	if (SFI::sf_IsDelayed( x.xs_model))
-	{	if (!consSet && !defTyping)				// 	(MH_S0513 also used in cncult3)
+	{	if (!consSet && xc != C_EXCNDCH_GROUND && !defTyping)				// 	(MH_S0513 also used in cncult3)
 			ooer( SFI_SFCON, MH_S0513,	// "Can't use delayed (massive) sfModel=%s without giving sfCon"
 				getChoiTx( SFX( MODEL)));
 	}
@@ -684,7 +699,7 @@ RC SFI::sf_CkfSURF(		// surface checker
 
 // sf_CkfSURF: require construction or u value, not both
 	BOO uSet = IsSet( SFI_SFU);
-	if (!consSet && !uSet && !defTyping)
+	if (!consSet && !uSet && xc!=C_EXCNDCH_GROUND && !defTyping)
 		rc |= oer( MH_S0417);  	// "Neither sfCon nor sfU given"
 	else if (consSet && uSet)
 		rc |= oer( MH_S0418);   // "Both sfCon and sfU given"
@@ -708,17 +723,17 @@ RC SFI::sf_CkfSURF(		// surface checker
 	{
 		if (IsSet(SFI_SFFND) && sfTy != C_OSTYCH_FLR)
 		{
-			oer("Only floor surfaces are allowed to reference 'sfFnd'. <> Is not a floor."); // TODO add formatted string
+			oer("Only floor surfaces are allowed to reference 'sfFnd'. '%s' Is not a floor.", Name());
 		}
 
 		if (IsSet(SFI_SFFNDFLOOR) && sfTy != C_OSTYCH_WALL)
 		{
-			oer("Only wall surfaces are allowed to reference 'sfFndFloor'. <> Is not a wall."); // TODO add formatted string
+			oer("Only wall surfaces are allowed to reference 'sfFndFloor'. '%s' Is not a wall.", Name());
 		}
 
 		if (IsSet(SFI_SFFND) && !IsSet(SFI_SFEXPPERIM))
 		{
-			oer("'sfExpPerim' must be set for foundaiton floors (i.e., when 'sfFnd' is set)."); // TODO add formatted string
+			oer("'sfExpPerim' must be set for foundation floors (i.e., when 'sfFnd' is set).");
 		}
 
 		// TODO: Checks for exposed perimeter...
@@ -3119,7 +3134,6 @@ makAncXSRAT(XsB, nullptr);			// runtime XSURFs: radiant/conductive coupling-to-a
 makAncWSHADRAT(WshadR, nullptr);	// Window shading info: entry for each window that has fin and/or overhang(s).
 									//    Accessed via subscript in XSURF.iwshad.
 makAncMSRAT(MsR, nullptr);			// Masses
-makAncKIVA(KvR, nullptr);			// Kiva Instances
 makAncSGRAT(SgR, nullptr);			// Solar gains for current month/season, calculated when month or season
 									//   [or other input] changes.
 									// 

src/cncult2.cpp

@@ -1415,7 +1415,7 @@ LOCAL RC topFnd()		// foundations
 			Kiva::Foundation::DGB_FIXED_TEMPERATURE;
 
 		kFnd->wall.heightAboveGrade = LIPtoSI(fnd->fd_wlHtAbvGrd);
-		kFnd->wall.depthBelowSlab = LIPtoSI(fnd->fd_wlDpBlwSlb);
+		// kFnd->wall.depthBelowSlab = LIPtoSI(fnd->fd_wlDpBlwSlb); // Set based on slab width in cncult3.cpp
 
 		kFnd->mesh.minCellDim = LIPtoSI(Top.tp_grndMinDim);
 		kFnd->mesh.maxNearGrowthCoeff = Top.tp_grndMaxGrthCoeff;