Issue2302 building time series enhancement (lbl-srg#3165)

* Make revisions * Update reference results * Fix default bindings & parameter names [ci skip] - Improve documentation of formerly example models that were made generic. * Restore parameter names, update doc * Edit documentation * Update doc, add dialog Advanced tab * Update release and revision notes [ci skip] * Update unit test results * Fix html * Update reference results for Examples * Add parameters for reference term unit conditions and update docs * Remove BOM * Change ref. conditions, use h in cooling [ci skip] * Update reference results * Revise release notes * Removed abs function and added assertions This ensures that all parameters indeed have the right signs Co-authored-by: AntoineGautier <[email protected]> Co-authored-by: Michael Wetter <[email protected]>
modelon-community · Jan 21, 2023 · e87617c · e87617c
1 parent 32610ca
commit e87617c
Show file tree

Hide file tree

Showing 11 changed files with 365 additions and 203 deletions.
diff --git a/Buildings/Experimental/DHC/Loads/BaseClasses/Examples/BaseClasses/BuildingTimeSeries.mo b/Buildings/Experimental/DHC/Loads/BaseClasses/Examples/BaseClasses/BuildingTimeSeries.mo
@@ -18,18 +18,24 @@ model BuildingTimeSeries
     annotation (Evaluate=true, Dialog(group="Configuration"));
   parameter String filNam
     "File name with thermal loads as time series";
-  parameter Real facMulHea=1
+  parameter Real facMulHea=QHea_flow_nominal /
+    (QHea_flow_nominal_ref * abs(T_aLoaHea_nominal - T_aHeaWat_nominal) /
+     abs(T_aLoaHea_nominal_ref - T_aHeaWat_nominal_ref) *
+     mLoaHea_flow_nominal / mLoaHea_flow_nominal_ref)
     "Heating terminal unit multiplier factor"
-    annotation(Dialog(enable=have_heaWat, group="Scaling"));
-  parameter Real facMulCoo=1
+    annotation(Dialog(enable=have_heaWat, group="Scaling", tab="Advanced"));
+  parameter Real facMulCoo=QCoo_flow_nominal /
+    (QCoo_flow_nominal_ref * abs(h_aLoaCoo_nominal - hSat_nominal) /
+     abs(h_aLoaCoo_nominal_ref - hSat_nominal_ref) *
+     mLoaCoo_flow_nominal / mLoaCoo_flow_nominal_ref)
     "Cooling terminal unit scaling factor"
-    annotation(Dialog(enable=have_chiWat, group="Scaling"));
-  parameter Modelica.Units.SI.Temperature T_aHeaWat_nominal=313.15
+    annotation(Dialog(enable=have_chiWat, group="Scaling", tab="Advanced"));
+  parameter Modelica.Units.SI.Temperature T_aHeaWat_nominal=323.15
     "Heating water inlet temperature at nominal conditions"
     annotation (Dialog(group="Nominal condition", enable=have_heaWat));
   parameter Modelica.Units.SI.Temperature T_bHeaWat_nominal(
     min=273.15,
-    displayUnit="degC") = T_aHeaWat_nominal - 5
+    displayUnit="degC") = T_aHeaWat_nominal - 10
     "Heating water outlet temperature at nominal conditions"
     annotation (Dialog(group="Nominal condition", enable=have_heaWat));
   parameter Modelica.Units.SI.Temperature T_aChiWat_nominal=280.15
@@ -42,36 +48,68 @@ model BuildingTimeSeries
     annotation (Dialog(group="Nominal condition", enable=have_chiWat));
   parameter Modelica.Units.SI.Temperature T_aLoaHea_nominal=293.15
     "Load side inlet temperature at nominal conditions in heating mode"
-    annotation (Dialog(group="Nominal condition"));
-  parameter Modelica.Units.SI.Temperature T_aLoaCoo_nominal=297.15
+    annotation (Dialog(group="Nominal condition", tab="Advanced"));
+  parameter Modelica.Units.SI.Temperature T_aLoaCoo_nominal=298.15
     "Load side inlet temperature at nominal conditions in cooling mode"
-    annotation (Dialog(group="Nominal condition", enable=have_chiWat));
-  parameter Modelica.Units.SI.MassFraction w_aLoaCoo_nominal=0.0095
+    annotation (Dialog(group="Nominal condition", tab="Advanced", enable=have_chiWat));
+  parameter Modelica.Units.SI.MassFraction w_aLoaCoo_nominal=0.01
     "Load side inlet humidity ratio at nominal conditions in cooling mode"
-    annotation (Dialog(group="Nominal condition", enable=have_chiWat));
-  parameter Modelica.Units.SI.MassFlowRate mLoaHea_flow_nominal=1
+    annotation (Dialog(group="Nominal condition", tab="Advanced", enable=have_chiWat));
+  parameter Modelica.Units.SI.MassFlowRate mLoaHea_flow_nominal(min=Modelica.Constants.eps)=0.5
     "Load side mass flow rate at nominal conditions in heating mode (single unit)"
-    annotation (Dialog(group="Nominal condition", enable=have_heaWat));
-  parameter Modelica.Units.SI.MassFlowRate mLoaCoo_flow_nominal=
-      mLoaHea_flow_nominal
+    annotation (Dialog(group="Nominal condition", tab="Advanced", enable=have_heaWat));
+  parameter Modelica.Units.SI.MassFlowRate mLoaCoo_flow_nominal(min=Modelica.Constants.eps)=
+    mLoaHea_flow_nominal
     "Load side mass flow rate at nominal conditions in cooling mode (single unit)"
-    annotation (Dialog(group="Nominal condition", enable=have_chiWat));
+    annotation (Dialog(group="Nominal condition", tab="Advanced", enable=have_chiWat));
+
+  parameter Modelica.Units.SI.Temperature T_aHeaWat_nominal_ref=323.15
+    "Heating water inlet temperature at nominal conditions of reference terminal unit"
+    annotation(Dialog(enable=have_heaWat, group="Reference terminal unit performance", tab="Advanced"));
+  parameter Modelica.Units.SI.Temperature T_aLoaHea_nominal_ref=293.15
+    "Load side inlet temperature at nominal conditions in heating mode of reference terminal unit"
+    annotation(Dialog(enable=have_heaWat, group="Reference terminal unit performance", tab="Advanced"));
+  parameter Modelica.Units.SI.MassFlowRate mLoaHea_flow_nominal_ref(min=Modelica.Constants.eps) = 0.5
+    "Load side mass flow rate at nominal conditions in heating mode of reference terminal unit"
+    annotation(Dialog(enable=have_heaWat, group="Reference terminal unit performance", tab="Advanced"));
+  parameter Modelica.Units.SI.HeatFlowRate QHea_flow_nominal_ref(min=Modelica.Constants.eps) = 4.5E3
+    "Heat flow at nominal conditions in heating mode of reference terminal unit"
+    annotation(Dialog(enable=have_heaWat, group="Reference terminal unit performance", tab="Advanced"));
+
+  parameter Modelica.Units.SI.Temperature T_aChiWat_nominal_ref=279.15
+    "Chilled water inlet temperature at nominal conditions of reference terminal unit"
+    annotation(Dialog(enable=have_chiWat, group="Reference terminal unit performance", tab="Advanced"));
+  parameter Modelica.Units.SI.Temperature T_aLoaCoo_nominal_ref=298.15
+    "Load side inlet temperature at nominal conditions in cooling mode of reference terminal unit"
+    annotation(Dialog(enable=have_chiWat, group="Reference terminal unit performance", tab="Advanced"));
+  parameter Modelica.Units.SI.MassFraction w_aLoaCoo_nominal_ref=0.01
+    "Load side inlet humidity ratio at nominal conditions in cooling mode of reference terminal unit"
+    annotation(Dialog(enable=have_chiWat, group="Reference terminal unit performance", tab="Advanced"));
+  parameter Modelica.Units.SI.MassFlowRate mLoaCoo_flow_nominal_ref(min=Modelica.Constants.eps) = 0.5
+    "Load side mass flow rate at nominal conditions in cooling mode of reference terminal unit"
+    annotation(Dialog(enable=have_chiWat, group="Reference terminal unit performance", tab="Advanced"));
+  parameter Modelica.Units.SI.HeatFlowRate QCoo_flow_nominal_ref(max=-Modelica.Constants.eps) = -5.8E3
+    "Heat flow at nominal conditions in cooling mode of reference terminal unit"
+    annotation(Dialog(enable=have_chiWat, group="Reference terminal unit performance", tab="Advanced"));
+
   parameter Modelica.Units.SI.HeatFlowRate QCoo_flow_nominal(max=-Modelica.Constants.eps)=
-       Buildings.Experimental.DHC.Loads.BaseClasses.getPeakLoad(string=
-    "#Peak space cooling load", filNam=Modelica.Utilities.Files.loadResource(
-    filNam)) "Design cooling heat flow rate (<=0)"
+    Buildings.Experimental.DHC.Loads.BaseClasses.getPeakLoad(string=
+    "#Peak space cooling load",
+    filNam=Modelica.Utilities.Files.loadResource(filNam))
+    "Design cooling heat flow rate (<=0)"
     annotation (Dialog(group="Nominal condition", enable=have_chiWat));
   parameter Modelica.Units.SI.HeatFlowRate QHea_flow_nominal(min=Modelica.Constants.eps)=
-       Buildings.Experimental.DHC.Loads.BaseClasses.getPeakLoad(string=
-    "#Peak space heating load", filNam=Modelica.Utilities.Files.loadResource(
-    filNam)) "Design heating heat flow rate (>=0)"
+    Buildings.Experimental.DHC.Loads.BaseClasses.getPeakLoad(string=
+    "#Peak space heating load",
+    filNam=Modelica.Utilities.Files.loadResource(filNam))
+    "Design heating heat flow rate (>=0)"
     annotation (Dialog(group="Nominal condition"));
-  parameter Modelica.Units.SI.MassFlowRate mChiWat_flow_nominal=abs(
-      QCoo_flow_nominal/cp_default/(T_aChiWat_nominal - T_bChiWat_nominal))
+  parameter Modelica.Units.SI.MassFlowRate mChiWat_flow_nominal(min=Modelica.Constants.eps)=
+      QCoo_flow_nominal/cp_default/(T_aChiWat_nominal - T_bChiWat_nominal)
     "Chilled water mass flow rate at nominal conditions (all units)"
     annotation (Dialog(group="Nominal condition"));
-  parameter Modelica.Units.SI.MassFlowRate mHeaWat_flow_nominal=abs(
-      QHea_flow_nominal/cp_default/(T_aHeaWat_nominal - T_bHeaWat_nominal))
+  parameter Modelica.Units.SI.MassFlowRate mHeaWat_flow_nominal(min=Modelica.Constants.eps)=
+      QHea_flow_nominal/cp_default/(T_aHeaWat_nominal - T_bHeaWat_nominal)
     "Heating water mass flow rate at nominal conditions (all units)"
     annotation (Dialog(group="Nominal condition"));
   parameter Real k(
@@ -163,8 +201,6 @@ model BuildingTimeSeries
     "Chilled water distribution system"
     annotation (Placement(transformation(extent={{120,-270},{140,-250}})));
   replaceable Buildings.Experimental.DHC.Loads.BaseClasses.Validation.BaseClasses.FanCoil2PipeCooling terUniCoo(
-    final QHea_flow_nominal=QHea_flow_nominal/facMulHea,
-    final T_aLoaHea_nominal=T_aLoaHea_nominal,
     final k=k,
     final Ti=Ti,
     final TRooHea_nominal=T_aLoaHea_nominal,
@@ -203,6 +239,48 @@ model BuildingTimeSeries
   Buildings.Controls.OBC.CDL.Continuous.MultiplyByParameter mulQReqCoo_flow(u(
         final unit="W"), final k=facMul) if have_cooLoa "Scaling"
     annotation (Placement(transformation(extent={{272,-10},{292,10}})));
+protected
+  parameter Modelica.Units.SI.AbsolutePressure pSat_nominal=
+    Buildings.Utilities.Psychrometrics.Functions.saturationPressure(T_aChiWat_nominal)
+    "Saturation pressure at entering water temperature";
+  parameter Modelica.Units.SI.AbsolutePressure pSat_nominal_ref=
+    Buildings.Utilities.Psychrometrics.Functions.saturationPressure(T_aChiWat_nominal_ref)
+    "Saturation pressure at entering water temperature for reference terminal unit";
+  parameter Modelica.Units.SI.MassFraction X1_aLoaCoo_nominal=
+     w_aLoaCoo_nominal / (1 + w_aLoaCoo_nominal)
+     "Water vapor concentration in [kg/kg total air]";
+  parameter Modelica.Units.SI.MassFraction X1Sat_nominal=
+    Buildings.Utilities.Psychrometrics.Functions.X_pSatpphi(
+      pSat=pSat_nominal, p=Medium2.p_default, phi=1.0)
+    "Water vapor concentration at saturation in [kg/kg total air]";
+  parameter Modelica.Units.SI.MassFraction X1_aLoaCoo_nominal_ref=
+     w_aLoaCoo_nominal_ref / (1 + w_aLoaCoo_nominal_ref)
+     "Water vapor concentration in [kg/kg total air]";
+  parameter Modelica.Units.SI.MassFraction X1Sat_nominal_ref=
+    Buildings.Utilities.Psychrometrics.Functions.X_pSatpphi(
+      pSat=pSat_nominal_ref, p=Medium2.p_default, phi=1.0)
+    "Water vapor concentration at saturation in [kg/kg total air]";
+  parameter Modelica.Units.SI.SpecificEnthalpy h_aLoaCoo_nominal=
+    Buildings.Media.Air.specificEnthalpy_pTX(
+      p=Medium2.p_default, T=T_aLoaCoo_nominal, X={X1_aLoaCoo_nominal, 1-X1_aLoaCoo_nominal})
+    "Specific enthalpy of enytering air at nominal conditions in cooling mode";
+  parameter Modelica.Units.SI.SpecificEnthalpy hSat_nominal=
+    Buildings.Media.Air.specificEnthalpy_pTX(
+      p=Medium2.p_default, T=T_aChiWat_nominal, X={X1Sat_nominal, 1-X1Sat_nominal})
+    "Specific enthalpy of saturated air at entering water temperature in cooling mode";
+  parameter Modelica.Units.SI.SpecificEnthalpy h_aLoaCoo_nominal_ref=
+    Buildings.Media.Air.specificEnthalpy_pTX(
+      p=Medium2.p_default, T=T_aLoaCoo_nominal_ref, X={X1_aLoaCoo_nominal_ref, 1-X1_aLoaCoo_nominal_ref})
+    "Specific enthalpy of enytering air at nominal conditions for reference terminal unit";
+  parameter Modelica.Units.SI.SpecificEnthalpy hSat_nominal_ref=
+    Buildings.Media.Air.specificEnthalpy_pTX(
+      p=Medium2.p_default, T=T_aChiWat_nominal_ref, X={X1Sat_nominal_ref, 1-X1Sat_nominal_ref})
+    "Specific enthalpy of saturated air at entering water temperature for reference terminal unit";
+initial equation
+  assert(QCoo_flow_nominal < -Modelica.Constants.eps, "QCoo_flow_nominal must be negative.");
+  assert(T_aChiWat_nominal - T_bChiWat_nominal < 0, "Temperature difference (T_aChiWat_nominal - T_bChiWat_nominal) has wrong sign.");
+  assert(T_aHeaWat_nominal - T_bHeaWat_nominal > 0, "Temperature difference (T_aHeaWat_nominal - T_bHeaWat_nominal) has wrong sign.");
+
 equation
   connect(terUniHea.port_bHeaWat,disFloHea.ports_a1[1])
     annotation (Line(points={{90,-20.3333},{90,-20},{146,-20},{146,-54},{140,
@@ -271,18 +349,62 @@ equation
           -66},{220,-66},{220,280},{268,280}}, color={0,0,127}));
   connect(disFloCoo.QActTot_flow, mulQCoo_flow.u) annotation (Line(points={{141,
           -266},{224,-266},{224,240},{268,240}}, color={0,0,127}));
-    annotation (Line(points={{90.8333,-12},{180,-12},{180,126},{238,126}},color={0,0,127}),
+annotation (
     Documentation(
-      info="
-<html>
+      info="<html>
+<p>
+This is a simplified building model where the space heating and cooling 
+loads are provided as time series. In order to approximate the emission 
+characteristic of the building HVAC system,
+this model uses idealized fan coil models that are parameterized with 
+the peak load, determined from the provided time series, and design 
+values of the hot water and chilled water supply and return temperatures. 
+</p>
+<h4>Implementation details</h4>
 <p>
-This is a simplified building model where the space heating and cooling loads
-are provided as time series.
+The total space heating (resp. cooling) load is split between
+<code>facMulHea</code> (resp. <code>facMulCoo</code>)
+identical terminal units with heat transfer performance approximated based on 
+design specifications of a reference terminal unit.
+It is not expected that the user modifies the default values 
+that are proposed for <code>facMulHea</code> and <code>facMulCoo</code>
+unless detailed design data are available for the building 
+HVAC system.
+In that latter case, the following set of parameters should be 
+modified consistently to match the design data.
+</p>
+<ul>
+<li>Hot water (resp. chilled water) supply and return temperature
+<code>T_aHeaWat_nominal</code> and <code>T_bHeaWat_nominal</code>
+(resp. <code>T_aChiWat_nominal</code> and <code>T_bChiWat_nominal</code>)
+</li>
+<li>Terminal unit entering air temperature <code>T_aLoaHea_nominal</code>
+(resp. <code>T_aLoaCoo_nominal</code>) and humidity ratio
+<code>w_aLoaCoo_nominal</code>
+</li>
+<li>Terminal unit air mass flow rate <code>mLoaHea_flow_nominal</code>
+(resp. <code>mLoaCoo_flow_nominal</code>)
+</li>
+<li>Terminal unit scaling factor <code>facMulHea</code>
+(resp. <code>facMulCoo</code>)
+</li>
+</ul>
+<p>
+For reference, the default reference terminal unit performance is based on 
+manufacturer data (Carrier fan coil model 42NL/NH) at selection conditions
+as specified in the \"Advanced\" tab.
 </p>
 </html>",
-      revisions="<html>
+revisions="<html>
 <ul>
 <li>
+November 21, 2022, by David Blum:<br/>
+Scale <code>facMulHea</code> and <code>facMulCoo</code> with peak load.<br/>
+This is for
+<a href=\"https://github.com/lbl-srg/modelica-buildings/issues/2302\">
+issue 2302</a>.
+</li>
+<li>
 December 21, 2020, by Antoine Gautier:<br/>
 Refactored for optional hot water and multiplier factor.<br/>
 This is for <a href=\"https://github.com/lbl-srg/modelica-buildings/issues/2291\">issue 2291</a>.

diff --git a/Buildings/Experimental/DHC/Loads/BaseClasses/Examples/CouplingTimeSeries.mo b/Buildings/Experimental/DHC/Loads/BaseClasses/Examples/CouplingTimeSeries.mo
@@ -8,8 +8,6 @@ model CouplingTimeSeries
     "Period for time averaged variables";
   Buildings.Experimental.DHC.Loads.BaseClasses.Examples.BaseClasses.BuildingTimeSeries bui(
     filNam="modelica://Buildings/Resources/Data/Experimental/DHC/Loads/Examples/SwissResidential_20190916.mos",
-    facMulHea=10,
-    facMulCoo=40,
     nPorts_aHeaWat=1,
     nPorts_aChiWat=1,
     nPorts_bHeaWat=1,
@@ -139,6 +137,13 @@ secondary pumps.
       revisions="<html>
 <ul>
 <li>
+November 21, 2022, by David Blum:<br/>
+Change <code>bui.facMulHea</code> and <code>bui.facMulCoo</code> to be default.<br/>
+This is for
+<a href=\"https://github.com/lbl-srg/modelica-buildings/issues/2302\">
+issue 2302</a>.
+</li>
+<li>
 February 21, 2020, by Antoine Gautier:<br/>
 First implementation.
 </li>

diff --git a/Buildings/Experimental/DHC/Loads/BaseClasses/Examples/CouplingTimeSeriesSingleLoop.mo b/Buildings/Experimental/DHC/Loads/BaseClasses/Examples/CouplingTimeSeriesSingleLoop.mo
@@ -9,7 +9,6 @@ model CouplingTimeSeriesSingleLoop
   Buildings.Experimental.DHC.Loads.BaseClasses.Examples.BaseClasses.BuildingTimeSeries buiCoo(
     have_heaWat=false,
     filNam="modelica://Buildings/Resources/Data/Experimental/DHC/Loads/Examples/SwissResidential_20190916.mos",
-    facMulCoo=40,
     nPorts_aChiWat=1,
     nPorts_bChiWat=1)
     "Building wint cooling only"
@@ -46,7 +45,6 @@ model CouplingTimeSeriesSingleLoop
   Buildings.Experimental.DHC.Loads.BaseClasses.Examples.BaseClasses.BuildingTimeSeries buiHea(
     have_chiWat=false,
     filNam="modelica://Buildings/Resources/Data/Experimental/DHC/Loads/Examples/SwissResidential_20190916.mos",
-    facMulHea=10,
     nPorts_aChiWat=1,
     nPorts_bChiWat=1,
     nPorts_aHeaWat=1,
@@ -146,6 +144,13 @@ secondary pumps.
       revisions="<html>
 <ul>
 <li>
+November 21, 2022, by David Blum:<br/>
+Change <code>buiHea.facMulHea</code> and <code>buiCoo.facMulCoo</code> to be default.<br/>
+This is for
+<a href=\"https://github.com/lbl-srg/modelica-buildings/issues/2302\">
+issue 2302</a>.
+</li>
+<li>
 September 18, 2020, by Jianjun Hu:<br/>
 First implementation.
 </li>

diff --git a/Buildings/Experimental/DHC/Loads/BaseClasses/PartialTerminalUnit.mo b/Buildings/Experimental/DHC/Loads/BaseClasses/PartialTerminalUnit.mo
@@ -500,9 +500,9 @@ in consistency with
 Buildings.Experimental.DHC.Loads.BaseClasses.FlowDistribution</a>.
 This requirement only applies to the source side.
 On the load side one is free to use whatever option suitable for the modeling needs.
-Note that typically for an air flow network connected to the outdoor
+Note that typically for an air flow network connected to the outdoor air
 (either at the room level for modeling infiltration or at the system level
-for the fresh air source), the unidirectional air flow condition cannot be guaranted.
+for the fresh air source), the unidirectional air flow condition cannot be guaranteed.
 The reason is the varying pressure of the outdoor air that can lead to a negative
 pressure difference at the terminal unit boundaries when the fan is off.
 </li>
@@ -536,6 +536,8 @@ and serving <i>multiple identical loads</i> (e.g., a thermal zone representing a
 </li>
 </ul>
 <p>
+Note that the two multiplier factors serve different modeling purposes.
+As such they typically should not be used simultaneously.
 Both multiplier factors are of type real (as opposed to integer) to allow
 for instance modeling a set of terminal units based on manufacturer data,
 while still being able to size the full set based on a peak load.

diff --git a/Buildings/Experimental/DHC/Loads/BaseClasses/Validation/BaseClasses/FanCoil2PipeCooling.mo b/Buildings/Experimental/DHC/Loads/BaseClasses/Validation/BaseClasses/FanCoil2PipeCooling.mo
@@ -19,6 +19,8 @@ model FanCoil2PipeCooling
     final have_TSen=false,
     final have_weaBus=false,
     final have_pum=false,
+    final QHea_flow_nominal=0,
+    final T_aLoaHea_nominal=293.15,
     mChiWat_flow_nominal=abs(
       QCoo_flow_nominal/cpChiWat_nominal/(T_aChiWat_nominal-T_bChiWat_nominal)));
   import hexConfiguration=Buildings.Fluid.Types.HeatExchangerConfiguration;
@@ -186,7 +188,7 @@ equation
     Documentation(
       info="<html>
 <p>
-This is a sensible only simplified model of a two-pipe fan coil unit for cooling.
+This is a simplified model of a two-pipe fan coil unit for cooling.
 It is intended to be used
 </p>
 <ul>
@@ -202,9 +204,6 @@ it therefore computes the water mass flow rate required to meet the load.
 </li>
 </ul>
 <p>
-For the sake of simplicity, a sensible only heat exchanger model is considered.
-</p>
-<p>
 For the sake of computational performance, a PI controller is used instead of an inverse
 model of the heat exchanger to assess the required water mass flow rate.
 The controller output signal is mapped linearly to both,