lbl-srg · mwetter · Aug 18, 2021 · Mar 14, 2021 · Mar 17, 2021 · Mar 17, 2021
diff --git a/Buildings/BoundaryConditions/GroundTemperature/BaseClasses/package.mo b/Buildings/BoundaryConditions/GroundTemperature/BaseClasses/package.mo
@@ -0,0 +1,18 @@
+within Buildings.BoundaryConditions.GroundTemperature;
+package BaseClasses "Package with base classes for Buildings.BoundaryConditions.GroundTemperature"
+  extends Modelica.Icons.BasesPackage;
+
+  annotation (Documentation(info="<html>
+<p>
+This package contains base classes that are used to construct the models in
+<a href=\"modelica://Buildings.BoundaryConditions.GroundTemperature\">Buildings.BoundaryConditions.GroundTemperature</a>.
+</p>
+</html>", revisions="<html>
+<ul>
+<li>
+May 19, 2021, by Baptiste Ravache:<br/>
+First implementation.
+</li>
+</ul>
+</html>"));
+end BaseClasses;
diff --git a/Buildings/BoundaryConditions/GroundTemperature/BaseClasses/package.order b/Buildings/BoundaryConditions/GroundTemperature/BaseClasses/package.order
@@ -0,0 +1 @@
+surfaceTemperature
diff --git a/Buildings/BoundaryConditions/GroundTemperature/BaseClasses/surfaceTemperature.mo b/Buildings/BoundaryConditions/GroundTemperature/BaseClasses/surfaceTemperature.mo
@@ -0,0 +1,100 @@
+within Buildings.BoundaryConditions.GroundTemperature.BaseClasses;
+function surfaceTemperature
+  "Function to correct the climatic constants using n-factors"
+  extends Modelica.Icons.Function;
+
+  input ClimaticConstants.Generic cliCon
+    "Surface temperature climatic conditions";
+  input Real nFacTha "Thawing n-factor (Tair > 0degC)";
+  input Real nFacFre "Freezing n-factor (Tair <= 0degC)";
+  output ClimaticConstants.Generic corCliCon
+    "Corrected surface temperature climatic conditions";
+
+protected
+  constant Integer Year=365 "Year period in days";
+  constant Integer secInDay = 24 * 60 * 60 "Seconds in a day";
+  constant Modelica.SIunits.Angle pi = Modelica.Constants.pi;
+  constant Modelica.SIunits.Temperature TFre = 273.15 "Freezing temperature of water";
+  Real freq = 2 * pi / Year "Year frequency in rad/days";
+  Modelica.SIunits.Temperature TAirDayMea[Year] "Daily mean air temperature (surface = 0 from uncorrected climatic constants)";
+  Modelica.SIunits.Temperature TSurDayMea[Year] "Daily mean corrected surface temperature";
+  Real C1;
+  Real C2;
+
+algorithm
+  // Analytical mean by integrating undisturbed soil temperature formula
+  TAirDayMea := {cliCon.TSurMea + cliCon.TSurAmp / freq * (
+    cos(freq * (cliCon.sinPha / secInDay - day)) -
+    cos(freq * (cliCon.sinPha / secInDay - (day + 1))))
+    for day in 1:Year};
+
+  TSurDayMea := {
+    if TAirDayMea[day] > TFre
+    then (TFre + (TAirDayMea[day] - TFre) * nFacTha)
+    else (TFre + (TAirDayMea[day] - TFre) * nFacFre)
+    for day in 1:Year};
+  C1 := sum({TSurDayMea[day] * cos(freq * day) for day in 1:Year});
+  C2 := sum({TSurDayMea[day] * sin(freq * day) for day in 1:Year});
+
+  corCliCon := ClimaticConstants.Generic(
+    TSurMea = sum(TSurDayMea)/Year,
+    TSurAmp = 2 / Year .* (C1^2 + C2^2)^0.5,
+    sinPha = (Modelica.Math.atan(C2 / C1) + pi/2) * secInDay / freq);
+
+  annotation (Documentation(revisions="<html>
+<ul>
+<li>
+May 19, 2021, by Baptiste Ravache:<br/>
+First implementation.
+</li>
+</ul>
+</html>", info="<html>
+<p>
+This function corrects the surface temperature climatic constants
+by applying n-factors with the methodology prescribed in the
+<i>District Cooling Guide</i> (ASHRAE, 2013).
+</p>
+<p>
+N-factors corresponds to the ratio of freezing (/thawing) degree
+days or index between the air and the ground surface and can
+be used to couple the air and ground surface temperatures.<br>
+For example, a freezing n-factor of 1.35 means that during the 
+freezing season, the daily average ground surface temperature is 
+on average 1.35 times colder than the air (using the freezing 
+temperature of water as a reference).<br>
+In its guide, ASHRAE suggests to first apply the n-factors to the
+uncorrected ground temperature at zero burial depth, and to fit a
+new sinusoidal curve to the result.
+<br>
+In this function, the freezing n-factor is applied to days where
+the daily mean air temperature is below the freezing temperature (0degC), 
+whereas the thawing n-factor is applied to the remaining days.
+</p>
+<p align=\"center\" style=\"font-style:italic;\">
+  T<sub>ground</sub> - T<sub>freezing</sub> = &eta;<sub>freezing</sub> * (T<sub>air</sub> - T<sub>freezing</sub>) &nbsp; if T<sub>air</sub> &lt;= T<sub>freezing</sub><br>
+  T<sub>ground</sub> - T<sub>freezing</sub> = &eta;<sub>thawing</sub> * (T<sub>air</sub> - T<sub>freezing</sub>) &nbsp;  if T<sub>air</sub> &gt; T<sub>freezing</sub>
+</p>
+<p>
+The sinusoidal curve is then fitted using the analytical solution
+proposed in Appendix B of the District Heating Guide.
+</p>
+<p>
+N-factors are specific to a climate and surface cover, and should be
+extrapolated from other sites with caution. As a first approximation,
+tabulated values of n-factors are available in Lunardini (1981) and 
+Freitag and McFadden (1997).
+</p>
+
+
+<h4>References</h4>
+<p>
+ASHRAE (2013). <i>District Cooling Guide</i>. ASHRAE, Atlanta, GA.<br>
+ASHRAE (2013). <i>District Heating Guide</i>. ASHRAE, Atlanta, GA.<br>
+D.W. Riseborough (2003). <i>Thawing and freezing indices in the active layer</i>. Proceedings of the 8th International Conference on Permafrost, Swets &amp; Zeitlinger.<br>
+V.J. Lunardini (1981). <i>Heat Transfer in Cold Climates</i>. Van Nostrand Reinhold Company.<br>
+D.R. Freitag and T. McFadden (1997). <i>Introduction to Cold Regions Engineering</i>. American Society of Civil Engineers.
+
+</p>
+
+</html>"));
+end surfaceTemperature;
diff --git a/Buildings/BoundaryConditions/GroundTemperature/ClimaticConstants.mo b/Buildings/BoundaryConditions/GroundTemperature/ClimaticConstants.mo
@@ -0,0 +1,49 @@
+within Buildings.BoundaryConditions.GroundTemperature;
+package ClimaticConstants "Surface temperature climatic constants"
+  extends Modelica.Icons.MaterialPropertiesPackage;
+
+  record Boston =
+      Buildings.BoundaryConditions.GroundTemperature.ClimaticConstants.Generic
+      (
+      TSurMea=284.23,
+      TSurAmp=11.57,
+      sinPha=9944640)        "Boston";
+  record Generic "Generic climatic constants"
+    extends Modelica.Icons.Record;
+    parameter Modelica.SIunits.Temperature TSurMea
+      "Mean annual surface temperature";
+    parameter Modelica.SIunits.TemperatureDifference TSurAmp
+      "Surface temperature amplitude";
+    parameter Modelica.SIunits.Duration sinPha(displayUnit="d")
+      "Phase lag of soil surface temperature";
+
+  end Generic;
+
+  record NewYork =
+      Buildings.BoundaryConditions.GroundTemperature.ClimaticConstants.Generic
+      (
+      TSurMea=286.03,
+      TSurAmp=11.45,
+      sinPha=9728640)        "New York";
+  record SanFrancisco =
+      Buildings.BoundaryConditions.GroundTemperature.ClimaticConstants.Generic
+      (
+      TSurMea=287.64,
+      TSurAmp=3.35,
+      sinPha=10419840)       "San Francisco";
+  annotation (Documentation(info="<html>
+<p>
+Surface temperature data that is used in the calculation of undisturbed soil temperature.
+See <a href=\"https://tc0602.ashraetcs.org/Climatic_constants_using_ASHRAE_CD_Ver_6.0.pdf\">
+Climatic Constants for Calculating Subsurface Soil Temperatures</a> for
+more information and a table of values.
+</p>
+</html>", revisions="<html>
+<ul>
+<li>
+March 17, 2021, by Baptiste Ravache:<br/>
+First implementation.
+</li>
+</ul>
+</html>"));
+end ClimaticConstants;
diff --git a/Buildings/BoundaryConditions/GroundTemperature/Examples/CorrectedConvection.mo b/Buildings/BoundaryConditions/GroundTemperature/Examples/CorrectedConvection.mo
@@ -0,0 +1,22 @@
+within Buildings.BoundaryConditions.GroundTemperature.Examples;
+model CorrectedConvection
+  "Example model for undisturbed soil temperature with surface convection correction"
+  extends UndisturbedSoilTemperature(TSoi(each useCon=true, each hSur=5));
+  annotation (Documentation(revisions="<html>
+<ul>
+<li>
+May 21, 2021, by Baptiste Ravache:<br/>
+First implementation.
+</li>
+</ul>
+</html>", info="<html>
+<p>
+This example model showcases the use of the convection coefficient
+correction, which allows to specify the heat transfer rate between
+the air and the surface temperature.
+</p>
+</html>"),
+experiment(StopTime=31536000, Tolerance=1e-6),
+__Dymola_Commands(file="modelica://Buildings/Resources/Scripts/Dymola/BoundaryConditions/GroundTemperature/Examples/CorrectedConvection.mos"
+        "Simulate and plot"));
+end CorrectedConvection;
diff --git a/Buildings/BoundaryConditions/GroundTemperature/Examples/CorrectedNFactors.mo b/Buildings/BoundaryConditions/GroundTemperature/Examples/CorrectedNFactors.mo
@@ -0,0 +1,30 @@
+within Buildings.BoundaryConditions.GroundTemperature.Examples;
+model CorrectedNFactors
+  "Example model for undisturbed soil temperature with n-factors correction"
+  extends UndisturbedSoilTemperature(
+    TSoi(each useNFac=true, each nFacTha=1.7, each nFacFre=0.66));
+  annotation (Documentation(revisions="<html>
+<ul>
+<li>
+May 21, 2021, by Baptiste Ravache:<br/>
+First implementation.
+</li>
+</ul>
+</html>", info="<html>
+<p>
+This example model showcases the use of n-factors, which are used
+to correct the surface temperature given the ratio of freezing/thawing
+degree days (FDD/TDD) between the air and the ground.
+</p>
+
+<h4>References</h4>
+<p>
+The values used in this example are equivalent to the use-case
+presented in the \"Heat Transfer at Ground Surface\" section of the
+<i>District Cooling Guide</i> (ASHRAE, 2013). 
+</p>
+</html>"),
+experiment(StopTime=31536000, Tolerance=1e-6),
+__Dymola_Commands(file="modelica://Buildings/Resources/Scripts/Dymola/BoundaryConditions/GroundTemperature/Examples/CorrectedNFactors.mos"
+        "Simulate and plot"));
+end CorrectedNFactors;
diff --git a/Buildings/BoundaryConditions/GroundTemperature/Examples/UndisturbedSoilTemperature.mo b/Buildings/BoundaryConditions/GroundTemperature/Examples/UndisturbedSoilTemperature.mo
@@ -0,0 +1,37 @@
+within Buildings.BoundaryConditions.GroundTemperature.Examples;
+model UndisturbedSoilTemperature "Example model for undisturbed soil temperature"
+  extends Modelica.Icons.Example;
+
+  parameter Integer nSoi = 4 "Number of probed depths";
+  parameter Modelica.SIunits.Length dep[nSoi] = {0,2,5,9} "Probed depths";
+
+  Buildings.BoundaryConditions.GroundTemperature.UndisturbedSoilTemperature
+    TSoi[nSoi](dep=dep, each cliCon=cliCon, each soiDat=soiDat)
+    "Undisturbed soil temperatures"
+    annotation (Placement(transformation(extent={{-20,-20},{20,20}})));
+
+protected
+  replaceable parameter ClimaticConstants.Boston cliCon
+    "Surface temperature climatic conditions";
+  replaceable parameter Buildings.HeatTransfer.Data.Soil.Generic soiDat(
+    k=1.58,c=1150,d=1600) "Soil thermal properties";
+  annotation (Icon(coordinateSystem(preserveAspectRatio=false)), Diagram(
+        coordinateSystem(preserveAspectRatio=false)),
+    experiment(StopTime=31536000, Tolerance=1e-6),
+    Documentation(info="<html>
+<p>
+This example model illustrates how the undisturbed soil temperature model 
+decreases seasonal temperature oscillations and increases delay as depth is 
+increasing.
+</p>
+</html>", revisions="<html>
+<ul>
+<li>
+March 17, 2021, by Baptiste Ravache:<br/>
+First implementation.
+</li>
+</ul>
+</html>"),
+    __Dymola_Commands(file="modelica://Buildings/Resources/Scripts/Dymola/BoundaryConditions/GroundTemperature/Examples/UndisturbedSoilTemperature.mos"
+        "Simulate and plot"));
+end UndisturbedSoilTemperature;
diff --git a/Buildings/BoundaryConditions/GroundTemperature/Examples/package.mo b/Buildings/BoundaryConditions/GroundTemperature/Examples/package.mo
@@ -0,0 +1,19 @@
+within Buildings.BoundaryConditions.GroundTemperature;
+package Examples "Collection of models that illustrate model use and test models"
+  extends Modelica.Icons.ExamplesPackage;
+
+  annotation (Documentation(info="<html>
+<p>
+This package contains examples for the use of models that can be found in
+<a href=\"modelica://Buildings.BoundaryConditions.GroundTemperature\">
+Buildings.BoundaryConditions.GroundTemperature</a>.
+</p>
+</html>", revisions="<html>
+<ul>
+<li>
+March 17, 2021, by Baptiste Ravache:<br/>
+First implementation.
+</li>
+</ul>
+</html>"));
+end Examples;
diff --git a/Buildings/BoundaryConditions/GroundTemperature/Examples/package.order b/Buildings/BoundaryConditions/GroundTemperature/Examples/package.order
@@ -0,0 +1,3 @@
+CorrectedConvection
+CorrectedNFactors
+UndisturbedSoilTemperature