Merge pull request #10138 from NREL/5114327-EarthTube1DVerticalEnhanc…

…ement

Add Vertical (1-D) Solution to Earth Tube Object

.gitignore

@@ -89,3 +89,4 @@ dist
 # if you generate sphinx docs, it builds a dummy version of the schema in the idd folder, just ignore it
 /idd/Energy+.schema.epJSON
 /idd/Energy+.schema.epJSON.in
+design/FY2023/earth_tube_solution_space_diagram.pdf

doc/input-output-reference/src/overview/group-airflow.tex

@@ -1752,11 +1752,40 @@ \subsubsection{Inputs}
 
 This number is the ``D'' parameter in the above earth tube equation. It is part of the user specified modifying parameters that are a function of environmental factors. This parameter is modified by square of the speed of wind being experienced outside the building. The units for this parameter are s\(^{2}\)/m\(^{2}\).
 
+\paragraph{Field: Earth Tube Model Type}\label{field-earth-tube-model-type}
+
+This field determines which modeling technique will be used to assess the performance of the earth tube.  The options are: Simple and Vertical.  In the Simple modeling approach, the temperature of the soil at the earth tube is approximated by the undisturbed ground conditions.  In the Vertical modeling approach, the temperature of the soil around the earth tube is modeled using a finite difference scheme to account for the impact of the earth tube on the surrounding soil conditions in a single direction (1-D).  For more information on the model type, reference the Earth Tube section of the EnergyPlus Engineering Reference.  This input is optional, and the default value is Simple.
+
+\paragraph{Field: Earth Tube Model Parameters}\label{field-earth-tube-model-parameters}
+
+This field refers to separate input syntax (see below) that is used for controlling parameters for the 1-D (Vertical) solution technique.  This input field is ignored for the Simple model.  If the user selects the Vertical solution and leaves this field blank, the default values for all of the parameters will be assumed.
+
+\paragraph{ZoneEarthtube:Parameters}\label{field-earth-tube-parameters}
+For the 1-D (Vertical) model, some additional optional parameters are available for the user to potentially control the solution space (number of nodes, distances) for the finite difference solution.  These are described below.
+
+\paragraph{Field: Earth Tube Parameters Name}\label{field-earth-tube-parameters-name}
+This name is used as a reference in the main EarthTube input syntax.  It is used to identify the parameters that the user desires to use to control what is being modeled and how detailed the model is.
+
+\paragraph{Field: Earth Tube Nodes Above}\label{field-earth-tube-nodes-above}
+This parameter sets the number of nodes above the earth tube, between the earth tube and the ground surface.  It has a minimum of three nodes and a maximum of ten nodes.  These limits were chosen to avoid the extremes of excessive execution times and overly simplified results.  The default value for this parameter is 5 (nodes).
+
+\paragraph{Field: Earth Tube Nodes Below}\label{field-earth-tube-nodes-below}
+This parameter sets the number of nodes below the earth tube, between the earth tube and the deep ground boundary.  It has a minimum of three nodes and a maximum of ten nodes.  These limits were chosen to avoid the extremes of excessive execution times and overly simplified results.  The default value for this parameter is 3 (nodes) or the minimum.
+
+\paragraph{Field: Earth Tube Dimensionless Boundary Above}\label{field-earth-tube-dimensionless-boundary-above}
+This parameter sets the dimensionless distance above the earth tube for the solution space.  The maximum value is 1.0, and the minimum value is 0.25.  When this parameter is set to 1.0, the upper boundary is set to be half of the diameter below the ground surface and the solution space thickness above the earth tube is the depth of the earth tube minus the earth tube diameter.  This maximum distance (earth tube depth minus diameter) is multiplied by this parameter to constrain the solution space to less than the maximum (when the parameter is less than 1.0).    The default value for this parameter is 1.0 (the maximum value).
+
+\paragraph{Field: Earth Tube Dimensionless Boundary Below}\label{field-earth-tube-dimensionless-boundary-below}
+This parameter sets the dimensionless distance below the earth tube for the solution space.  The maximum value is 1.0, and the minimum value is 0.25.  This parameter is interpretted in a similar fashion as the previous parameter where the depth of the solution space below the earth tube is determined by the maximum distance above the earth tube (earth tube depth minus radius).  This allows the user to have different thickness for the modeled portion of the ground above and below the earth tube.  The default value for this parameter is 0.25 (the minimum value).
+
+\paragraph{Field: Earth Tube Dimensionless Solution Space Width}\label{field-earth-tube-dimensionless-solution-space-width}
+This parameter sets the dimensionless width of the solution space horizontally as a function of the earth tube radius as defined in the main earth tube input syntax.  The maximum value is 20.0, and the minimum value is 3.0.  The default value for this parameter is 4.0 which means that the width of the solution space is four times the radius.  In other words, this would include soil one radius length beyond the edges of the tube on either side of the earth tube.
+
 An IDF example:
 
 \begin{lstlisting}
 
-EARTHTUBE,
+ZoneEarthtube,
   Zone 2,           !- Zone Name
   Simple EarthTube, !- Schedule Name
   3.425198,         !- Design Volume Flow Rate
@@ -1775,10 +1804,20 @@ \subsubsection{Inputs}
   15.0,             !- Average Soil Surface Temperature
   5.6,              !- Amplitude of Soil Surface Temperature
   0.0,              !- Phase Constant of Soil Surface Temperature
-  0.6060000    ,    !- Constant Term Flow Coef
+  0.6060000,        !- Constant Term Flow Coef
   2.0199999E-02,    !- Temp Term Flow Coef
   5.9800001E-04,    !- Velocity Term Flow Coef
-  0.0000000E+00;    !- Velocity**2 Term Flow Coef
+  0.0000000E+00,    !- Velocity**2 Term Flow Coef
+  Vertical,         !- Earth Tube Model Type
+  EarthTubeParams;  !- Earth Tube Model Parameters
+
+ZoneEarthtube:Parameters,
+  EarthTubeParams,  !- Earth Tube Model Parameters (Name)
+  5,                !- Nodes Above Earth Tube
+  3,                !- Nodes Below Earth Tube
+  1.0,              !- Earth Tube Dimensionless Boundary Above
+  0.5,              !- Earth Tube Dimensionless Boundary Below
+  4.0;              !- Earth Tube Dimensionless Solution Space Width
 \end{lstlisting}
 
 \subsubsection{Outputs}\label{zoneearthtube-outputs}
@@ -1820,6 +1859,14 @@ \subsubsection{Outputs}\label{zoneearthtube-outputs}
   HVAC,Average,Earth Tube Inlet Wet Bulb Temperature {[}C{]}
 \item
   HVAC,Average,Earth Tube Inlet Humidity Ratio {[}kgWater/kgDryAir{]}
+\item
+  Zone,Average,Earth Tube Node Temperature <X> {[}C{]}
+\item
+  Zone,Average,Earth Tube Undisturbed Ground Temperature <X> {[}C{]}
+\item
+  Zone,Average,Earth Tube Upper Boundary Ground Temperature {[}C{]}
+\item
+  Zone,Average,Earth Tube Lower Boundary Ground Temperature {[}C{]}
 \end{itemize}
 
 \paragraph{Earth Tube Zone Sensible Cooling Energy {[}J{]}}\label{earth-tube-zone-sensible-cooling-energy-j}
@@ -1884,6 +1931,22 @@ \subsubsection{Outputs}\label{zoneearthtube-outputs}
 
 This is the humidity ratio of the air entering the zone after passing through the earth tube {[}kgWater/kgDryAir{]}.
 
+\paragraph{Earth Tube Node Temperature <X> {[}C{]}}\label{earth-tube-node-temperatures-c}
+
+This will generate the internal node temperatures {[}C{]} for the earth tube as a result of the 1-D finite difference model.  This is only valid for the 1-D (Vertical) model.
+
+\paragraph{Earth Tube Undisturbed Ground Temperature <X> {[}C{]}}\label{earth-tube-undisturbed-node-temperatures-c}
+
+This will report the theoretical undisturbed ground temperature at the location of the internal node temperatures {[}C{]} as well as the average for the location of the earth tube for the 1-D finite difference model.  This is only valid for the 1-D (Vertical) model and provides a comparison of conditions for the simple model and the 1-D (Vertical) model.
+
+\paragraph{Earth Tube Upper Boundary Ground Temperature {[}C{]}}\label{earth-tube-upper-boundary-temperature-c}
+
+This will report the theoretical undisturbed ground temperature at the upper boundary for the 1-D finite difference model.  This is only valid for the 1-D (Vertical) model.
+
+\paragraph{Earth Tube Lower Boundary Ground Temperature {[}C{]}}\label{earth-tube-lower-boundary-temperature-c}
+
+This will report the theoretical undisturbed ground temperature at the lower boundary for the 1-D finite difference model.  This is only valid for the 1-D (Vertical) model.
+
 \subsection{ZoneCoolTower:Shower}\label{zonecooltowershower}
 
 A cooltower (which is sometimes referred to as a wind tower or a shower cooling tower) is a component that is intended to model a passive downdraught evaporative cooling (PDEC) that is designed to capture the wind at the top of a tower and cool the outside air using water evaporation before delivering it to a space.~ The air flow in these systems is natural as the evaporation process increases the density of the air causing it to fall through the tower and into the space without the aid of a fan. ~A cooltower typically consists of a water spray or an evaporative pad, a shaft, and a water tank or reservoir. ~Wind catchers to improve the wind-driven performance at the top of the tower are optional. ~Water is pumped over an evaporative device by water pump which is the only component consumed power for this system.~ This water cools and humidifies incoming air and then the cool, dense air naturally falls down through shaft and leaves through large openings at the bottom of cooltowers.

idd/Energy+.idd.in

@@ -24527,10 +24527,58 @@ ZoneEarthtube,
       \note  "C" in Equation
       \type real
       \default 0
- N18; \field Velocity Squared Term Flow Coefficient
+ N18, \field Velocity Squared Term Flow Coefficient
       \note  "D" in Equation
       \type real
       \default 0
+ A5,  \field Earth Tube Model Type
+      \type choice
+      \key Basic
+      \key Vertical
+      \default Basic
+ A6;  \field Earth Tube Model Parameters
+      \type object-list
+      \object-list EarthTubeParameterNames
+
+ZoneEarthtube:Parameters,
+      \memo Parameters that apply to the vertical model for an earth tube
+ \min-fields 6
+ A1,  \field Earth Tube Model Parameters Name
+      \required-field
+      \reference EarthTubeParameterNames
+ N1,  \field Nodes Above Earth Tube
+      \type integer
+      \units dimensionless
+      \minimum 3
+      \maximum 10
+      \default 5
+ N2,  \field Nodes Below Earth Tube
+      \type integer
+      \units dimensionless
+      \minimum 3
+      \maximum 10
+      \default 3
+ N3,  \field Earth Tube Dimensionless Boundary Above
+      \note When set to 1.0, the upper boundary is one earth tube radius below ground.
+      \type real
+      \units dimensionless
+      \minimum 0.25
+      \maximum 1.0
+      \default 1.0 
+ N4,  \field Earth Tube Dimensionless Boundary Above
+      \note When set to 1.0, the upper boundary is one earth tube radius below ground.
+      \type real
+      \units dimensionless
+      \minimum 0.25
+      \maximum 1.0
+      \default 0.25
+ N5;  \field Earth Tube Solution Space Width
+      \note Width of the nodes in the direction parallel to the ground, multiplied by earth tube radius
+      \type real
+      \units dimensionless
+      \minimum 3.0
+      \maximum 20.0
+      \default 4.0
 
 ZoneCoolTower:Shower,
      \memo A cooltower (sometimes referred to as a wind tower or a shower cooling tower)