Add object-level output variables for ZoneInfiltration

design/FY2021/ReportIndividualInfiltrationObject.md

@@ -0,0 +1,96 @@
+# Add ZoneInfiltration Output Variables for Individual objects(Issue #8209)
+================
+
+**Yueyue Zhou, NREL**
+
+ - 25 June 2021
+
+
+## Background ##
+
+Excerpts lifted from [issue #8209](https://github.com/NREL/EnergyPlus/issues/8209)
+
+ - There can be one infiltration object serving multiple zones, and there can be multiple infiltration objects serving the same zone. Currently the output variables only report at zone level, which is good for the first case. However, for the second case, there's no way to obtain, e.g., Sensible Heat Gain Energy specific to each object.
+ - Some related discussion in [Add Space PR](https://github.com/NREL/EnergyPlus/pull/8394#discussion_r530585696):
+	 - Dan Macumber: Is it possible to make infiltration or ventilation at the space level? That would simplify input for cases where ventilation requirements are a function of space type.
+	 - Jason Degraw: I think it is possible, I think we probably just want to avoid having both (e.g. SpaceInfiltration _and_ ZoneInfiltration). Moving everything to the space level will probably be more work, but if that's the right solution then we should do that.
+	 - Scott Horowitz: Whether it's SpaceInfiltration or ZoneInfiltration, it'd be nice to be able to get individual outputs for each object. With current EnergyPlus, you can have multiple ZoneInfiltration objects in a zone, but can only get aggregate outputs (i.e., the key for Zone Infiltration Sensible Heat Gain Energy is a zone object, not an infiltration object).
+	 - Richard Raustad: Should probably have outputs for both space and zone to show individual as well as aggregated.
+	 - Edwin Lee: I agree with this: limit to one input approach but output at both the space and zone level.
+
+
+## E-mail and  Conference Call Conclusions ##
+
+*None yet.*
+
+## Overview ##
+
+This work will implement code changes that calculate infiltration output variables at individual levels. Proposed list of variables to report is: 
+
+ - Infiltration Sensible Heat Loss Energy
+ - Infiltration Sensible Heat Gain Energy
+ - Infiltration Latent Heat Loss Energy
+ - Infiltration Latent Heat Gain Energy
+ - Infiltration Total Heat Loss Energy
+ - Infiltration Total Heat Gain Energy
+ - Infiltration Current Density Volume Flow Rate
+ - Infiltration Standard Density Volume Flow Rate
+ - Infiltration Current Density Volume
+ - Infiltration Standard Density Volume
+ - Infiltration Mass
+ - Infiltration Mass Flow Rate
+ - Infiltration Air Change Rate
+
+Considering the mapping of multiple infiltration and multiple zone, it might require two-level reporting, eg:
+1. **Infiltration1** is serving ThermalZoneList where **ThermalZone1** and **ThermalZone2** are included
+2. **Infiltration2** is serving **ThermalZone1** only
+
+Then we will want Sensible Heat Loss to be reported in the csv file with the format like (similar to how PEOPLE is reported):
+
+ - ThermalZone1 Infiltration1: Infiltiration Sensible Heat Loss Energy
+ - ThermalZone1 Infiltration2: Infiltiration Sensible Heat Loss Energy 
+ - ThermalZone2 Infiltration1: Infiltiration Sensible Heat Loss Energy .
+
+The impacted infiltration objects are:
+-   [ZoneInfiltration:DesignFlowRate](https://bigladdersoftware.com/epx/docs/9-4/input-output-reference/group-airflow.html#zoneinfiltrationdesignflowrate) (Primary)
+-   [ZoneInfiltration:EffectiveLeakageArea](https://bigladdersoftware.com/epx/docs/9-4/input-output-reference/group-airflow.html#zoneinfiltrationeffectiveleakagearea) (Optional depends on implementation)
+-   [ZoneInfiltration:FlowCoefficient](https://bigladdersoftware.com/epx/docs/9-4/input-output-reference/group-airflow.html#zoneinfiltrationflowcoefficient) (Optional depends on implementation)
+
+## Approach ##
+
+### Existing approach description ###
+
+Below description takes Infiltiration Sensible Heat Loss as an example: 
+Current E+ reported variable is **ZnAirRpt(ZoneLoop).InfilHeatLoss**, it is calcualted at *HVACManager.cc* function *ReportAirHeatBalance* with a zone loop, the equation is:
+
+    ZnAirRpt(ZoneLoop).InfilHeatLoss = 0.001 * state.dataHeatBalFanSys->MCPI(ZoneLoop) * (state.dataHeatBalFanSys->MAT(ZoneLoop) - Zone(ZoneLoop).OutDryBulbTemp) * TimeStepSys * DataGlobalConstants::SecInHour * 1000.0 * ADSCorrectionFactor;
+
+where the **state.dataHeatBalFanSys->MCPI(ZoneLoop)** is the summed (infiltration mass flow * air specific heat) at zone level, it is calculated at *ZoneEquipmentManager.cc* in function *CalcAirFlowSimple* , see:
+
+
+    In infiltration object loop (example of ZoneInfiltration:DesignFlowRate):
+	    NZ = state.dataHeatBal->Infiltration(j).ZonePtr; // zone index
+	    MCpI_temp = state.dataHeatBal->Infiltration(j).VolumeFlowRate * AirDensity * CpAir; 
+	    state.dataHeatBalFanSys->MCPI(NZ) += MCpI_temp;
+
+And data initialization of state.dataHeatBal->Infiltration is in HeatBalanceAirManager.cc
+
+### Proposed approach ###
+
+The idea is to follow how`People` object is implemented to report both individual and zone level outputs.
+
+The requested feature will be implemented by allocating new variable `state.dataHeatBal->Infiltration(NumInfil).HeatLoss`, etc. Since `state.dataHeatBal->Infiltration` already arranges and contains infiltration objects that only point to single zone (instead of zone or zone list), the total number of `state.dataHeatBal->Infiltration` should be equal to `state.dataHeatBal->TotInfiltration`. This structure will store calculated infiltration data at object level. It will be calculated at HVACManager.cc or ZoneEquipmentManager.cc or HeatBalanceAirManager.cc depending on detailed implementation.
+
+New variables will be set up for Infiltration objects. 
+
+## Testing
+
+No new example file needed. Assume it isn't supposed to be any diffs expected on ci testing. Local tests should verify that the new variables are able to be requested and reported correctly.
+
+## Input Output Reference Documentation ##
+
+Need to update the output descriptions for infiltration objects as reporting both at zone and individual object level.
+
+## IDD Changes and Transition
+
+None

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

@@ -413,6 +413,41 @@ \subsubsection{Inputs}\label{inputs-2-005}
 
 \subsubsection{Outputs}\label{outputs-003}
 
+Zone Infiltration objects have output variables for individual objects and for zone totals.
+
+Object level outputs include:
+
+\begin{itemize}
+\item
+  HVAC,Sum,Infiltration Sensible Heat Loss Energy {[}J{]}
+\item
+  HVAC,Sum,Infiltration Sensible Heat Gain Energy {[}J{]}
+\item
+  HVAC,Sum,Infiltration Latent Heat Loss Energy {[}J{]}
+\item
+  HVAC,Sum,Infiltration Latent Heat Gain Energy {[}J{]}
+\item
+  HVAC,Sum,Infiltration Total Heat Loss Energy {[}J{]}
+\item
+  HVAC,Sum,Infiltration Total Heat Gain Energy {[}J{]}
+\item
+  HVAC,Average,Infiltration Current Density Volume Flow Rate {[}m3/s{]}
+\item
+  HVAC,Average,Infiltration Standard Density Volume Flow Rate {[}m3/s{]}
+\item
+  HVAC,Sum,Infiltration Current Density Volume {[}m3{]}
+\item
+  HVAC,Sum,Infiltration Standard Density Volume {[}m3{]}
+\item
+  HVAC,Sum,Infiltration Mass {[}kg{]}
+\item
+  HVAC,Sum,Infiltration Mass Flow Rate {[}kg/s{]}
+\item
+  HVAC,Average,Infiltration Air Change Rate {[}ach{]}
+\end{itemize}
+
+Zone level outputs include:
+
 \begin{itemize}
 \item
   HVAC,Sum,Zone Infiltration Sensible Heat Loss Energy {[}J{]}

src/EnergyPlus/DataHeatBalance.hh

@@ -896,24 +896,41 @@ namespace DataHeatBalance {
         Real64 BasicStackCoefficient; // "Cs" Stack coefficient
         Real64 BasicWindCoefficient;  // "Cw" wind coefficient
         // Flow Coefficient, AIM-2, Walker and Wilson terms
-        Real64 FlowCoefficient;      // "c" Flow coefficient
-        Real64 AIM2StackCoefficient; // "Cs" stack coefficient
-        Real64 AIM2WindCoefficient;  // "Cw" wind coefficient
-        Real64 PressureExponent;     // "n" pressure power law exponent
-        Real64 ShelterFactor;        // "s" shelter factor
-        bool EMSOverrideOn;          // if true then EMS is requesting to override
-        Real64 EMSAirFlowRateValue;  // value EMS is setting for air flow rate
-        bool QuadratureSum;          // If quadrature sum of zone air balance method is used
-        int OABalancePtr;            // A pointer to ZoneAirBalance If quadrature is true
-        Real64 VolumeFlowRate;       // infiltration air volume flow rate
-        Real64 MassFlowRate;         // infiltration air mass flow rate
+        Real64 FlowCoefficient;       // "c" Flow coefficient
+        Real64 AIM2StackCoefficient;  // "Cs" stack coefficient
+        Real64 AIM2WindCoefficient;   // "Cw" wind coefficient
+        Real64 PressureExponent;      // "n" pressure power law exponent
+        Real64 ShelterFactor;         // "s" shelter factor
+        bool EMSOverrideOn;           // if true then EMS is requesting to override
+        Real64 EMSAirFlowRateValue;   // value EMS is setting for air flow rate
+        bool QuadratureSum;           // If quadrature sum of zone air balance method is used
+        int OABalancePtr;             // A pointer to ZoneAirBalance If quadrature is true
+        Real64 VolumeFlowRate;        // infiltration air volume flow rate
+        Real64 MassFlowRate;          // infiltration air mass flow rate
+        Real64 MCpI_temp;             // INFILTRATION MASS FLOW * AIR SPECIFIC HEAT
+        Real64 InfilHeatGain;         // Heat Gain {J} due to infiltration
+        Real64 InfilHeatLoss;         // Heat Loss {J} due to infiltration
+        Real64 InfilLatentGain;       // Latent Gain {J} due to infiltration
+        Real64 InfilLatentLoss;       // Latent Loss {J} due to infiltration
+        Real64 InfilTotalGain;        // Total Gain {J} due to infiltration (sensible+latent)
+        Real64 InfilTotalLoss;        // Total Loss {J} due to infiltration (sensible+latent)
+        Real64 InfilVolumeCurDensity; // Volume of Air {m3} due to infiltration at current zone air density
+        Real64 InfilVolumeStdDensity; // Volume of Air {m3} due to infiltration at standard density (adjusted for elevation)
+        Real64 InfilVdotCurDensity;   // Volume flow rate of Air {m3/s} due to infiltration at current zone air density
+        Real64 InfilVdotStdDensity;   // Volume flow rate of Air {m3/s} due to infiltration standard density (adjusted elevation)
+        Real64 InfilMdot;             // Mass flow rate {kg/s} due to infiltration for reporting
+        Real64 InfilMass;             // Mass of Air {kg} due to infiltration
+        Real64 InfilAirChangeRate;    // Infiltration air change rate {ach}
 
         // Default Constructor
         InfiltrationData()
             : ZonePtr(0), SchedPtr(0), ModelType(0), DesignLevel(0.0), ConstantTermCoef(0.0), TemperatureTermCoef(0.0), VelocityTermCoef(0.0),
               VelocitySQTermCoef(0.0), LeakageArea(0.0), BasicStackCoefficient(0.0), BasicWindCoefficient(0.0), FlowCoefficient(0.0),
               AIM2StackCoefficient(0.0), AIM2WindCoefficient(0.0), PressureExponent(0.0), ShelterFactor(0.0), EMSOverrideOn(false),
-              EMSAirFlowRateValue(0.0), QuadratureSum(false), OABalancePtr(0), VolumeFlowRate(0.0), MassFlowRate(0.0)
+              EMSAirFlowRateValue(0.0), QuadratureSum(false), OABalancePtr(0), VolumeFlowRate(0.0), MassFlowRate(0.0), MCpI_temp(0.0),
+              InfilHeatGain(0.0), InfilHeatLoss(0.0), InfilLatentGain(0.0), InfilLatentLoss(0.0), InfilTotalGain(0.0), InfilTotalLoss(0.0),
+              InfilVolumeCurDensity(0.0), InfilVolumeStdDensity(0.0), InfilVdotCurDensity(0.0), InfilVdotStdDensity(0.0), InfilMdot(0.0),
+              InfilMass(0.0), InfilAirChangeRate(0.0)
         {
         }
     };