Merge branch 'develop' into DirectSolution-in-new-DX-coil

cmake/PythonSetupAPIinBuild.cmake

@@ -21,4 +21,5 @@ configure_file( "${API_SOURCE_DIR}/api.py" "${API_TARGET_DIR}/api.py" )
 configure_file( "${API_SOURCE_DIR}/func.py" "${API_TARGET_DIR}/func.py" )
 configure_file( "${API_SOURCE_DIR}/runtime.py" "${API_TARGET_DIR}/runtime.py" )
 configure_file( "${API_SOURCE_DIR}/plugin.py" "${API_TARGET_DIR}/plugin.py" )
+configure_file( "${API_SOURCE_DIR}/state.py" "${API_TARGET_DIR}/state.py" )
 configure_file( "${API_SOURCE_DIR}/__init__.py" "${API_TARGET_DIR}/__init__.py" )

datasets/StandardReports.idf

@@ -207,13 +207,13 @@
     SumOrAverage,            !- Aggregation Type for Variable or Meter 1
     Diesel:Facility,         !- Variable or Meter 2 Name
     Maximum,                 !- Aggregation Type for Variable or Meter 2
-    FuelOil#1:Facility,      !- Variable or Meter 3 Name
+    FuelOilNo1:Facility,      !- Variable or Meter 3 Name
     SumOrAverage,            !- Aggregation Type for Variable or Meter 3
-    FuelOil#1:Facility,      !- Variable or Meter 4 Name
+    FuelOilNo1:Facility,      !- Variable or Meter 4 Name
     Maximum,                 !- Aggregation Type for Variable or Meter 4
-    FuelOil#2:Facility,      !- Variable or Meter 5 Name
+    FuelOilNo2:Facility,      !- Variable or Meter 5 Name
     SumOrAverage,            !- Aggregation Type for Variable or Meter 5
-    FuelOil#2:Facility,      !- Variable or Meter 6 Name
+    FuelOilNo2:Facility,      !- Variable or Meter 6 Name
     Maximum;                 !- Aggregation Type for Variable or Meter 6
 
   Output:Table:Monthly,
@@ -303,25 +303,25 @@
   Output:Table:Monthly,
     End-Use Energy Consumption - Fuel Oil,  !- Name
     ,                        !- Digits After Decimal
-    ExteriorEquipment:FuelOil#1,  !- Variable or Meter 1 Name
+    ExteriorEquipment:FuelOilNo1,  !- Variable or Meter 1 Name
     SumOrAverage,            !- Aggregation Type for Variable or Meter 1
-    Cooling:FuelOil#1,       !- Variable or Meter 2 Name
+    Cooling:FuelOilNo1,       !- Variable or Meter 2 Name
     SumOrAverage,            !- Aggregation Type for Variable or Meter 2
-    Heating:FuelOil#1,       !- Variable or Meter 3 Name
+    Heating:FuelOilNo1,       !- Variable or Meter 3 Name
     SumOrAverage,            !- Aggregation Type for Variable or Meter 3
-    WaterSystems:FuelOil#1,  !- Variable or Meter 4 Name
+    WaterSystems:FuelOilNo1,  !- Variable or Meter 4 Name
     SumOrAverage,            !- Aggregation Type for Variable or Meter 4
-    Cogeneration:FuelOil#1,  !- Variable or Meter 5 Name
+    Cogeneration:FuelOilNo1,  !- Variable or Meter 5 Name
     SumOrAverage,            !- Aggregation Type for Variable or Meter 5
-    ExteriorEquipment:FuelOil#2,  !- Variable or Meter 6 Name
+    ExteriorEquipment:FuelOilNo2,  !- Variable or Meter 6 Name
     SumOrAverage,            !- Aggregation Type for Variable or Meter 6
-    Cooling:FuelOil#2,       !- Variable or Meter 7 Name
+    Cooling:FuelOilNo2,       !- Variable or Meter 7 Name
     SumOrAverage,            !- Aggregation Type for Variable or Meter 7
-    Heating:FuelOil#2,       !- Variable or Meter 8 Name
+    Heating:FuelOilNo2,       !- Variable or Meter 8 Name
     SumOrAverage,            !- Aggregation Type for Variable or Meter 8
-    WaterSystems:FuelOil#2,  !- Variable or Meter 9 Name
+    WaterSystems:FuelOilNo2,  !- Variable or Meter 9 Name
     SumOrAverage,            !- Aggregation Type for Variable or Meter 9
-    Cogeneration:FuelOil#2,  !- Variable or Meter 10 Name
+    Cogeneration:FuelOilNo2,  !- Variable or Meter 10 Name
     SumOrAverage;            !- Aggregation Type for Variable or Meter 10
 
   Output:Table:Monthly,
@@ -453,25 +453,25 @@
   Output:Table:Monthly,
     Peak Energy End-Use - Fuel Oil,  !- Name
     ,                        !- Digits After Decimal
-    ExteriorEquipment:FuelOil#1,  !- Variable or Meter 1 Name
+    ExteriorEquipment:FuelOilNo1,  !- Variable or Meter 1 Name
     Maximum,                 !- Aggregation Type for Variable or Meter 1
-    Cooling:FuelOil#1,       !- Variable or Meter 2 Name
+    Cooling:FuelOilNo1,       !- Variable or Meter 2 Name
     Maximum,                 !- Aggregation Type for Variable or Meter 2
-    Heating:FuelOil#1,       !- Variable or Meter 3 Name
+    Heating:FuelOilNo1,       !- Variable or Meter 3 Name
     Maximum,                 !- Aggregation Type for Variable or Meter 3
-    WaterSystems:FuelOil#1,  !- Variable or Meter 4 Name
+    WaterSystems:FuelOilNo1,  !- Variable or Meter 4 Name
     Maximum,                 !- Aggregation Type for Variable or Meter 4
-    Cogeneration:FuelOil#1,  !- Variable or Meter 5 Name
+    Cogeneration:FuelOilNo1,  !- Variable or Meter 5 Name
     Maximum,                 !- Aggregation Type for Variable or Meter 5
-    ExteriorEquipment:FuelOil#2,  !- Variable or Meter 6 Name
+    ExteriorEquipment:FuelOilNo2,  !- Variable or Meter 6 Name
     Maximum,                 !- Aggregation Type for Variable or Meter 6
-    Cooling:FuelOil#2,       !- Variable or Meter 7 Name
+    Cooling:FuelOilNo2,       !- Variable or Meter 7 Name
     Maximum,                 !- Aggregation Type for Variable or Meter 7
-    Heating:FuelOil#2,       !- Variable or Meter 8 Name
+    Heating:FuelOilNo2,       !- Variable or Meter 8 Name
     Maximum,                 !- Aggregation Type for Variable or Meter 8
-    WaterSystems:FuelOil#2,  !- Variable or Meter 9 Name
+    WaterSystems:FuelOilNo2,  !- Variable or Meter 9 Name
     Maximum,                 !- Aggregation Type for Variable or Meter 9
-    Cogeneration:FuelOil#2,  !- Variable or Meter 10 Name
+    Cogeneration:FuelOilNo2,  !- Variable or Meter 10 Name
     Maximum;                 !- Aggregation Type for Variable or Meter 10
 
   Output:Table:Monthly,

design/FY2020/NFP-LowTempRadSysAddPipeAndContactResistance.md

@@ -0,0 +1,67 @@
+Addition of Pipe Wall and Pipe to Surface Contact Resistance to the Low Temperature Radiant
+================
+
+**Rick Strand, UIUC**
+
+ - Original Date: July 2, 2020
+ - Revision Date
+
+
+## Justification for New Feature ##
+
+Based on research that has been done in the past, the Center for the Built Environment at the University of California at Berkeley has identified some necessary improvements to the EnergyPlus low temperature radiant system models. These improvements would allow for more appropriate modeling of those systems in practice and would bring EnergyPlus up to date on current best practices in this area.  One of those areas of improvement in the EnergyPlus low temperature radiant system model is the characterization of heat transfer between the fluid being circulated through the system and the slab itself.  Currently, only the convection between fluid and the slab itself is taken into account.  When the model was created, it was assumed that the convection was the most important part and because the slab itself is very significant that other factors were not critical.  However, ISO 11855-2 does provide a method to for calculating resistance through the pipe wall and also contact resistance between the pipe and the slab.  It is uncertain as to how much of an impact this has on overall heat transfer.  However, in general, experience has shown that the convection itself provides very little resistance to heat transfer and the slab temperature is often nearly identical to the fluid outlet temperature.  So, implementing an improvement here would likely improve the accuracy of the model within EnergyPlus and bring the model in line with ISO.
+
+## E-mail and  Conference Call Conclusions ##
+
+External Communications: To date, the author has had contact with researchers at the CBE both via email and through a 2 hour Zoom meeting. As a result of the emails and the Zoom meeting, the author of this NFP created a “wishlist” document that summarized the request from CBE, the current status of the EnergyPlus code in relation to the CBE request, and an analysis of the potential implementation of the request in EnergyPlus (potential approach, priority, and estimated level of effort). Some of the information in this NFP is based on that “wishlist” document. That document was sent to the researchers from the CBE for their review, and the response was their support of the priorities and the approach as written.
+
+## Overview ##
+
+Overall, the task here is to implement aspects of ISO 11855-2 in the variable and constant flow low temperature radiant system models.  Using the information from the standard, the modeling of heat transfer between the fluid and the slab will be improved.  Specifically, the resistance in the pipe wall and the contact resistance between the pipe and the slab will be added to the current model.
+
+## Approach ##
+
+The current method for modeling heat transfer between the fluid in the piping and the radiant system is handled in a single subroutine and uses the effectiveness/NTU method for heat exchangers with the assumption that the slab is at a single temperature at the location of the piping.  In the existing code, the convection between the fluid in the piping and the slab is modeled using the Colburn equation, which is a relationship for convective heat transfer when a fluid flows inside a pipe.  This will be compared to the recommendations in ISO 118855-2.  If the ISO standard recommends a different equation, then that will be implemented if it is determined that it is better and meets the other assumptions of the existing radiant model.  In addition, the recommendations from ISO 11855-2 for heat transfer through the pipe material and the contact resistance will also be added to the resistance from the convective heat transfer to provide a combined resistance/heat transfer coefficient that includes all three of these effects.  For the piping, the user will be asked to specify the conductivity of the piping material and the inner and outer diameter of the piping.  Defaults for these parameters will be based on ISO 11855-2 for PEX piping, the most common material used in the radiant industry currently, and the pipe diameter parameters will be based on standard 1/2” PEX piping.  Note that the inner piping diameter is already part of the object definition in EnergyPlus so only two new parameters are needed.
+
+## Testing/Validation/Data Sources ##
+
+Standard unit test(s) will be used to verify that the components of the improved model are being evaluated properly.  Data for defaults will be based on ISO-11855-2.  Existing input files will be modified to use the default parameters.
+
+## Input Output Reference Documentation ##
+
+Additions will be made to the Input Output Reference for the three new model parameters.  Examples of how this will be integrated into the existing documentation as shown below.  Only new input will be needed.  No new output reporting will be necessary.  Note that the inside diameter already exists in EnergyPlus—the information below is simply a modification of the existing information.
+
+## Input Description ##
+
+\paragraph{Field: Hydronic Tubing Inside Diameter}\label{field-hydronic-tubing-inside-diameter-000}
+
+This field is the inside diameter of the tubes through which water is circulated for the system being defined by this statement. The inside diameter should be recorded in meters and is used to determine the convective heat transfer from the water to the inside surface of the hydronic tubing as well as the thickness of the pipe for conduction through the pipe wall.  The default value for this parameter is the value for common 1/2” piping or 0.012m.
+
+\paragraph{Field: Hydronic Tubing Outside Diameter}\label{field-hydronic-tubing-outside-diameter-000}
+
+This field is the outside diameter of the tubes through which water is circulated for the system being defined by this statement. The outside diameter should be recorded in meters and is used to determine the contact resistance between the pipe and the slab as well as the thickness of the pipe for conduction through the pipe wall.  The default value for this parameter is the value for common 1/2” piping or 0.016m.
+
+\paragraph{Field: Hydronic Tubing Conductivity}\label{field-hydronic-tubing-conductivity-000}
+
+This field is the conductivity of the piping material used in the radiant system in W/(m-K).  The default value for this parameter is 0.35 which is the approximation for most commonly used piping material (PEX tubing).
+
+
+## Outputs Description ##
+
+No new output descriptions are necessary for this work.
+
+## Engineering Reference ##
+
+A section will be added to the Engineering Reference to further explain the equations used in the updated model.  Currently in the ER, there is a section that describes the convection between the fluid and the pipe.  This will be expanded to include the new modeling equations that are taken from ISO 11855-2.
+
+## Example File and Transition Changes ##
+
+All existing input files that use either the variable or constant flow radiant systems will be enhanced to include the new input parameters.  Transition changes for the addition of these three new parameters will be added to the rule set for V9.4 and code will be added to the transition F90 code.
+
+## References ##
+
+Communications between the CBE and the author of this NFP are available upon request as is the summary of the features requested by the CBE and the status within EnergyPlus (wishlist).
+ISO Standard 11855-2.
+
+
+

doc/engineering-reference/src/loop-equipment-sizing-and-other-design-data/component-sizing.tex

@@ -2734,7 +2734,7 @@ \subsubsection{ZoneHVAC:LowTemperatureRadiant:VariableFlow}\label{zonehvaclowtem
 TubeLength = \frac{{TotalSurfaceArea}}{{TubeSpacing}}
 \end{equation}
 
-Note that tube spacing is assumed to be 0.15m.
+Note that tube spacing is determined by the Tube Spacing field of the Construction:InternalSource input used to define the radiant surface(s) of this system.  If the user has entered a spacing that is less than 0.01m or more than 1.0m, the sizing calculation will assume that the spacing is equal to 0.15m.
 
 \subsubsection{ZoneHVAC:LowTemperatureRadiant:ConstantFlow}\label{zonehvaclowtemperatureradiantconstantflow}
 

doc/engineering-reference/src/simulation-models-encyclopedic-reference-004/radiant-system-models.tex

@@ -639,9 +639,12 @@ \subsubsection{Heat Exchanger Formulation for Hydronic Systems}\label{heat-excha
 
 \begin{equation}
 NTU \equiv \frac{{UA}}{{{{\left( {\dot m{c_p}} \right)}_{water}}}}
+\label{eq:NTURadSysEquationGeneric}
 \end{equation}
 
-Since the water tubes were assumed to have no effect on the heat transfer process, the only term present in the overall heat transfer coefficient, UA, is a convection term.~ Thus, the equation for UA is:
+EnergyPlus includes two possible methods for calculating the heat exchange between the circulating fluid and the rest of the system and these are controlled by user input: {\emph{ConvectionOnly} and \emph{ISOStandard}.  Both are described in more detail below.
+
+\textbf{\emph{ConvectionOnly Heat Transfer Model}}.  In this model, the water tubes were assumed to have no effect on the heat transfer process.  So, the only term present in the overall heat transfer coefficient, UA, is a convection term.~ Thus, the equation for UA is:
 
 \begin{equation}
 UA = h\left( {\pi DL} \right)
@@ -672,6 +675,32 @@ \subsubsection{Heat Exchanger Formulation for Hydronic Systems}\label{heat-excha
 
 The parameter m is the absolute viscosity of water.~ For internal pipe flow, the flow is assumed to be turbulent for ReD \(\geq\) 2300.
 
+\textbf{\emph{ISOStandard Heat Transfer Model}}.  In this model, the convection between the fluid and the tubes and the conduction resistance of the tubes themselves are assumed to have an impact on the overall heat transfer.  The method used in EnergyPlus for this model is based on ISO Standard 11855-2(2012) which is entitled ``Building environment design — Design, dimensioning, installation and control of embedded radiant heating and cooling systems — Part 2: Determination of the design heating and cooling capacity''.  The key equations from the ISO Standard are summarized in Appendix B of Standard 11855-2 and are outlined below.
+
+In ISO Standard 11855-2, the heat convection for turbulent flow between the circulating fluid and the inside wall of the tube is characterized by the following equation:
+
+\begin{equation}
+{R_{conv}} = \frac{W^{0.13}}{8 \pi} {\left(\frac{D_{out}-D{in}}{\dot m L}\right)}^{0.87}
+\end{equation}
+
+where W is the tube separation in the direction perpendicular to the main heat transfer direction, \({D_{out}}\) is the outside tube diameter,  \({D_{in}}\) is the inside tube diameter,  \(\dot m\) is the fluid mass flow rate in the tube, and L is the tube length.
+
+The resistance of the pipe wall is characterized by this equation:
+
+\begin{equation}
+{R_{tube}} = \frac{W ln\frac{D_{out}}{D_{in}}}{2 \pi k_{tube}}
+\end{equation}
+
+where \(k_{tube}\) is the thermal conductivity of the tube material.
+
+Finally, the U-value for this model is calculated using:
+
+\begin{equation}
+U = \frac{1}{{R_{conv}} + {R_{tube}}}
+\end{equation}
+
+This U-value is then used in Equation~\ref{eq:NTURadSysEquationGeneric} to calculate NTU in the heat exchanger formulation shown above.
+
 Knowledge of the flow conditions allows Equations~\ref{eq:RadSysHX675} through~\ref{eq:RadSysHXReD681} to be calculated.~ This essentially eliminates \(\varepsilon\) as an unknown.~ The controls and the plant define the water mass flow rate and the inlet water temperature, leaving two equations (Equations~\ref{eq:RadSysHX673} and~\ref{eq:RadSysHX674}) and three unknowns.~ The third equation that can be used in conjunction with Equations~\ref{eq:RadSysHX673} and~\ref{eq:RadSysHX674} is Equation~\ref{eq:QTFDeriv672}, which is the CTF/QTF equation for the temperature at the source location.
 
 Knowing the inlet water temperature and water mass flow rate, the calculation procedure is somewhat involved and requires, in addition to Equations~\ref{eq:QTFDeriv672},~\ref{eq:RadSysHX673}, and~\ref{eq:RadSysHX674}, the use of a modified form of Equation~\ref{eq:LaplaceTransformDeriv653}.~ Equation~\ref{eq:LaplaceTransformDeriv653} is the standard conduction transfer function formula for a building element with an embedded source/sink of heat.~ In EnergyPlus, the surface flux on the left hand side of the equation is replaced with a surface heat balance:

doc/getting-started/src/energy-meters/custom-meters.tex

@@ -1,3 +1,3 @@
 \section{Custom Meters}\label{custom-meters}
 
-You can also define your own ``custom meters'' from variable names that are summed during the simulation.~ You assign the proper fuel type during the definition (review Input Output Reference, objects: \textbf{Meter:Custom} and \textbf{Meter:CustomDecrement}) for further requirements.
+You can also define your own ``custom meters'' from variable names that are summed during the simulation.~ You assign the proper resource type during the definition (review Input Output Reference, objects: \textbf{Meter:Custom} and \textbf{Meter:CustomDecrement}) for further requirements.