Space Sizing and HVAC Documentation and Unit Test Updates

doc/engineering-reference/src/integrated-solution-manager/basis-for-the-zone-and-air-system-integration.tex

@@ -1,6 +1,6 @@
 \section{Basis for the Zone and Air System Integration}\label{basis-for-the-zone-and-air-system-integration}
 
-The basis for the zone and air system integration is to formulate energy and moisture balances for the zone air and solve the resulting ordinary differential equations using a predictor-corrector approach. The formulation of the solution scheme starts with a heat balance on the zone air.
+The basis for the zone and air system integration is to formulate energy and moisture balances for the zone air and solve the resulting ordinary differential equations using a predictor-corrector approach. The formulation of the solution scheme starts with a heat balance on the zone air. If space heat balance is active, the same method applies to the space air.
 
 \begin{equation}
 {C_z}\frac{{d{T_z}}}{{dt}} = \sum\limits_{i = 1}^{{N_{sl}}} {{{\dot Q}_i}}  + \sum\limits_{i = 1}^{{N_{surfaces}}} {{h_i}} {A_i}\left( {{T_{si}} - {T_z}} \right) + \sum\limits_{i = 1}^{{N_{zones}}} {{{\dot m}_i}} {C_p}\left( {{T_{zi}} - {T_z}} \right)\, + {\dot m_{\inf }}{C_p}\left( {{T_\infty } - {T_z}} \right) + {\dot Q_{sys}}

doc/engineering-reference/src/integrated-solution-manager/summary-of-time-marching-solution.tex

@@ -66,6 +66,37 @@ \subsection{Simultaneous Solution of Plant/System Water Loop}\label{simultaneous
 
 Simultaneous solution of the system and plant operating parameters required that the temperature of the water entering the coils must be the same as the temperature leaving the chillers or boilers. In addition, the temperature of the return water from the coils must be equal to the chiller or boiler entering water temperature. In practice so long as the plant is not out of capacity the leaving water temperature from chillers and boilers is constant and equal to the design value. No iteration was required to match system and plant boundary conditions. However, if either the chiller or boiler plant was overloaded then the temperature of the water leaving the plant was not equal to the design value and the maximum output of the plant could change because of the off-design conditions. An iterative scheme using the secant method to predict successive updates to the plant leaving water conditions was therefore employed to solve for the water loop conditions with the plant operating at its maximum capacity. The simulation of the system and plant loops is described in greater detail in the later sections.
 
+\subsection{Space HVAC Simulation and Control}\label{space-hvac-simulation-and-control}
+When Space HVAC is simulated (see SpaceHVAC:EquipmentConnections), the HVAC equipment is modeled at the zone level as usual with adjustements made before and after the zone equipment simulation in function ZoneEquipmentManager:SimZoneEquipment. The space air temperatures and humidity will be calculated for each space along with lumped zone air conditions.
+
+\subsubsection{SpaceHVAC:ZoneEquipmentSplitter Adjustments}\label{space-hvac-zoneeqsplitter-adjustments}
+When a SpaceHVAC:ZoneEquipmentSplitter is used, the zone loads may be saved and adjusted prior to simulating a piece of zone equipment, according to the specified Thermostat Control Method. For Ideal control, no adjustement is made. For SingleSpace and Max control, the zone sensible and latent loads are save and then adjusted by the space load and the space fraction as shown below. Adjustments are made independently for sensible and latent loads.
+
+\begin{equation}
+{Ratio} = \dot Q_{space} / (SpaceFraction * {\dot Q_{zone}})
+\label{eq:SpaceHVACLoadAdjustment1}
+\end{equation}
+
+\begin{equation}
+{\dot Q_{adjusted}} = {Ratio}{\dot Q_{zone}} 
+\label{eq:SpaceHVACLoadAdjustment2}
+\end{equation}
+
+where:
+
+${\dot Q_{space}}$ is the remaining load (sensible or latent) for the control space
+
+${\dot Q_{zone}}$ is the remaining load (sensible or latent) for the zone
+
+$Ratio$ is the ratio applied to all load types for the zone (remaining, load to heating setpoint, load to cooling setpoint, and sequenced loads). 
+
+After the piece of zone equipment is simulated, any saved zone loads are restored, the equipment outlet node flow is distributed to the space outlet nodes, and any non-air system output is also distributed to the spaces. For the Ideal control option, the space fractions are recaculated every time step based on the current space load to zone load ratio.
+
+\subsubsection{SpaceHVAC:ZoneEquipmentMixer Adjustments}\label{space-hvac-zoneeqmixer-adjustments}
+When a SpaceHVAC:ZoneEquipmentMixer is used, before any zone HVAC equipment is simulated, the conditions on the mixer's zone equipment inlet node are set to the combined space outlet node conditions weighted by the space fractions.
+
+After all of the zone HVAC equipment is simulated, the flow rates on the space outlet nodes are set to the space fraction times the zone equipment inlet node flow rate.
+
 \subsection{References}\label{references-043}
 
 Ceylan, H. T., and G. E. Myers. 1980. Long-time Solutions to Heat Conduction Transients with Time-Dependent Inputs. ASME Journal of Heat Transfer, Volume 102, No. 1, pp.~115-120.

doc/input-output-reference/src/overview/group-simulation-parameters.tex

@@ -470,10 +470,10 @@ \subsubsection{Inputs}\label{inputs-8-023}
 Three choices are allowed to select which solution algorithm will be used. The \textbf{ThirdOrderBackwardDifference} selection is the default selection and uses the third order finite difference approximation to solve the zone air energy and moisture balance equations. The \textbf{AnalyticalSolution} selection uses the integration approach to solve the zone air energy and moisture balance equations. The \textbf{EulerMethod} selection uses the first order finite backward difference approximation to solve the zone air energy and moisture balance equations.
 
 \paragraph{Field: Do Space Heat Balance for Sizing}\label{field-do-space-heat-balance-sizing}
-If yes, space-level heat balance will be calculated and reported during sizing. If no, then only zone-level heat balance will be calculated. This field defaults to No. Note that space heat balance is not supported for \hyperref[inputs-hm]{HybridModel:Zone}, \hyperref[roomairmodeltype]{RoomAirModelType} other than Mixing, \hyperref[heatbalancealgorithm]{HeatBalanceAlgorithm} MoisturePenetrationDepthConductionTransferFunction and CombinedHeatAndMoistureFiniteElement.
+If yes, space-level heat balance will be calculated and reported during sizing, and space sizing results will be reported along with zone sizing results. If no, then only zone-level heat balance will be calculated. This field defaults to No. For zones with more than one space, the zone sizing results are calculated for the whole zone and represent the coincident peak for the spaces in the zone. Note that space heat balance is not supported for \hyperref[inputs-hm]{HybridModel:Zone}, \hyperref[roomairmodeltype]{RoomAirModelType} other than Mixing, \hyperref[heatbalancealgorithm]{HeatBalanceAlgorithm} MoisturePenetrationDepthConductionTransferFunction and CombinedHeatAndMoistureFiniteElement.
 
 \paragraph{Field: Do Space Heat Balance for Simulation}\label{field-do-space-heat-balance-simulation}
-If yes, space-level heat balance will be calculated and reported during the simulation. If no, then only zone-level heat balance will be calculated. This field defaults to No.
+If yes, space-level heat balance will be calculated and reported during the simulation. If no, then only zone-level heat balance will be calculated. This field defaults to No. When this field is Yes, optional SpaceHVAC objects may be used to distribute zone HVAC equipment output to the spaces in the zone. See \hyperref[spacehvacequipmentconnections]{SpaceHVAC:EquipmentConnections}, \hyperref[spacehvaczoneequipmentsplitter]{SpaceHVAC:ZoneEquipmentSplitter} and \hyperref[spacehvaczoneequipmentmixer]{SpaceHVAC:ZoneEquipmentMixer}.
 
 And, a default IDF example is shown below:
 

doc/input-output-reference/src/overview/group-zone-equipment.tex

@@ -388,7 +388,14 @@ \subsubsection{Inputs}\label{inputs-2-048}
 \subsection{SpaceHVAC:EquipmentConnections}\label{spacehvacequipmentconnections}
 
 If HVAC equipment is modeled at the Space level for one or more zones, the SpaceHVAC:EquipmentConnections statement defines the node connections to a space. Any space modeled with SpaceHVAC:EquipmentConnections will have its own air temperature and humidity ratio, and surfaces and internal gains in the zone will interact with the space conditions.
-Note that all nodes mentioned in the SpaceHVAC:EquipmentConnections input must be unique. That is, all nodes in all the SpaceHVAC:EquipmentConnections statements referenced by the ``Space Air Inlet Nodes'', ``Space Air Exhaust Nodes'', ``Space Air Node Name'' and ``Space Return Air Node Name'' cannot have any node name appearing more than once. Unlike ZoneHVAC:EquipmentConnections, there is no equipment list. Equipment is connected to spaces using \hyperref[spacehvaczoneequipmentsplitter]{SpaceHVAC:ZoneEquipmentSplitter}. If any space in a zone has a SpaceHVAC:EquipmentConnections object, then all spaces in that zone must have one, even if they are not served by any HVAC equipment. SpaceHVAC is only used when \hyperref[zoneairheatbalancealgorithm]{ZoneAirHeatBalanceAlgorithm} ``Do Space Heat Balance for Simulation'' is Yes. 
+Note that all nodes mentioned in the SpaceHVAC:EquipmentConnections input must be unique. That is, all nodes in all the SpaceHVAC:EquipmentConnections statements referenced by the ``Space Air Inlet Nodes'', ``Space Air Exhaust Nodes'', ``Space Air Node Name'' and ``Space Return Air Node Name'' cannot have any node name appearing more than once. Unlike ZoneHVAC:EquipmentConnections, there is no equipment list. Equipment is connected to spaces using \hyperref[spacehvaczoneequipmentsplitter]{SpaceHVAC:ZoneEquipmentSplitter} and \hyperref[spacehvaczoneequipmentmixer]{SpaceHVAC:ZoneEquipmentMixer} as shown in Figure \ref{fig:space-hvac-equipment-connections}. If any space in a zone has a SpaceHVAC:EquipmentConnections object, then all spaces in that zone must have one, even if they are not served by any HVAC equipment. SpaceHVAC is only used when \hyperref[zoneairheatbalancealgorithm]{ZoneAirHeatBalanceAlgorithm} ``Do Space Heat Balance for Simulation'' is Yes.
+
+\begin{figure}[hbtp]
+\centering
+\includegraphics[width=0.9\textwidth, height=0.9\textheight, keepaspectratio=true]{media/SpaceHVACSchematic2.png}
+\caption{Space HVAC Equipment Connections \protect \label{fig:space-hvac-equipment-connections}}
+\end{figure}
+
 
 \subsubsection{Inputs}\label{inputs-space-1-052}
 
@@ -492,7 +499,7 @@ \subsubsection{Inputs}\label{inputs-1-052-seqsplitter}
 
 \paragraph{Field: Space \textless{}x\textgreater{} Supply Node Name}\label{field-seqsplitter-space-supply-node-name}
 
-The name of a SpaceHVAC:EquipmentConnections Inlet Node Name that takes a fraction of the airflow from the Zone Equipment Output Node.
+The name of a \hyperref[spacehvacequipmentconnections]{SpaceHVAC:EquipmentConnections} Inlet Node Name that takes a fraction of the airflow from the Zone Equipment Outlet Node.
 Not used for non-airflow zone equipment.
 
 An example of this statement in an IDF is:
@@ -552,7 +559,7 @@ \subsubsection{Inputs}\label{inputs-1-052-seqmixer}
 
 \paragraph{Field: Space \textless{}x\textgreater{} Node Name}\label{field-seqmixer-space-node-name}
 
-The name of a SpaceHVAC:EquipmentConnections Exhaust Node Name that sends a fraction of the airflow to the Zone Equipment Output Node.
+The name of a \hyperref[spacehvacequipmentconnections]{SpaceHVAC:EquipmentConnections} Exhaust Node Name that sends a fraction of the airflow to the Zone Equipment Inlst Node.
 
 An example of this statement in an IDF is:
 

src/EnergyPlus/DataZoneEquipment.cc

@@ -1979,4 +1979,99 @@ void ZoneEquipmentSplitter::distributeOutput(EnergyPlusData &state,
     }
 }
 
+void EquipConfiguration::beginEnvirnInit(EnergyPlusData &state)
+{
+    auto &zoneNode = state.dataLoopNodes->Node(this->ZoneNode);
+    zoneNode.Temp = 20.0;
+    zoneNode.MassFlowRate = 0.0;
+    zoneNode.Quality = 1.0;
+    zoneNode.Press = state.dataEnvrn->OutBaroPress;
+    zoneNode.HumRat = state.dataEnvrn->OutHumRat;
+    zoneNode.Enthalpy = Psychrometrics::PsyHFnTdbW(zoneNode.Temp, zoneNode.HumRat);
+    if (state.dataContaminantBalance->Contaminant.CO2Simulation) {
+        zoneNode.CO2 = state.dataContaminantBalance->OutdoorCO2;
+    }
+    if (state.dataContaminantBalance->Contaminant.GenericContamSimulation) {
+        zoneNode.GenContam = state.dataContaminantBalance->OutdoorGC;
+    }
+
+    for (int const nodeNum : this->InletNode) {
+        auto &inNode = state.dataLoopNodes->Node(nodeNum);
+        inNode.Temp = 20.0;
+        inNode.MassFlowRate = 0.0;
+        inNode.Quality = 1.0;
+        inNode.Press = state.dataEnvrn->OutBaroPress;
+        inNode.HumRat = state.dataEnvrn->OutHumRat;
+        inNode.Enthalpy = Psychrometrics::PsyHFnTdbW(inNode.Temp, inNode.HumRat);
+        if (state.dataContaminantBalance->Contaminant.CO2Simulation) {
+            inNode.CO2 = state.dataContaminantBalance->OutdoorCO2;
+        }
+        if (state.dataContaminantBalance->Contaminant.GenericContamSimulation) {
+            inNode.GenContam = state.dataContaminantBalance->OutdoorGC;
+        }
+    }
+
+    for (int const nodeNum : this->ExhaustNode) {
+        auto &exhNode = state.dataLoopNodes->Node(nodeNum);
+        exhNode.Temp = 20.0;
+        exhNode.MassFlowRate = 0.0;
+        exhNode.Quality = 1.0;
+        exhNode.Press = state.dataEnvrn->OutBaroPress;
+        exhNode.HumRat = state.dataEnvrn->OutHumRat;
+        exhNode.Enthalpy = Psychrometrics::PsyHFnTdbW(exhNode.Temp, exhNode.HumRat);
+        if (state.dataContaminantBalance->Contaminant.CO2Simulation) {
+            exhNode.CO2 = state.dataContaminantBalance->OutdoorCO2;
+        }
+        if (state.dataContaminantBalance->Contaminant.GenericContamSimulation) {
+            exhNode.GenContam = state.dataContaminantBalance->OutdoorGC;
+        }
+    }
+
+    // BG CR 7122 following resets return air node.
+    int NumRetNodes = this->NumReturnNodes;
+    if (NumRetNodes > 0) {
+        for (int const nodeNum : this->ReturnNode) {
+            auto &returnNode = state.dataLoopNodes->Node(nodeNum);
+            returnNode.Temp = 20.0;
+            returnNode.MassFlowRate = 0.0;
+            returnNode.Quality = 1.0;
+            returnNode.Press = state.dataEnvrn->OutBaroPress;
+            returnNode.HumRat = state.dataEnvrn->OutHumRat;
+            returnNode.Enthalpy = Psychrometrics::PsyHFnTdbW(returnNode.Temp, returnNode.HumRat);
+            if (state.dataContaminantBalance->Contaminant.CO2Simulation) {
+                returnNode.CO2 = state.dataContaminantBalance->OutdoorCO2;
+            }
+            if (state.dataContaminantBalance->Contaminant.GenericContamSimulation) {
+                returnNode.GenContam = state.dataContaminantBalance->OutdoorGC;
+            }
+        }
+    }
+}
+
+void EquipConfiguration::hvacTimeStepInit(EnergyPlusData &state, bool FirstHVACIteration)
+{
+    auto &zoneNode = state.dataLoopNodes->Node(this->ZoneNode);
+    this->ExcessZoneExh = 0.0;
+
+    if (FirstHVACIteration) {
+        for (int const nodeNum : this->ExhaustNode) {
+            auto &exhNode = state.dataLoopNodes->Node(nodeNum);
+            exhNode.Temp = zoneNode.Temp;
+            exhNode.HumRat = zoneNode.HumRat;
+            exhNode.Enthalpy = zoneNode.Enthalpy;
+            exhNode.Press = zoneNode.Press;
+            exhNode.Quality = zoneNode.Quality;
+            exhNode.MassFlowRate = 0.0;
+            exhNode.MassFlowRateMaxAvail = 0.0;
+            exhNode.MassFlowRateMinAvail = 0.0;
+            if (state.dataContaminantBalance->Contaminant.CO2Simulation) {
+                exhNode.CO2 = zoneNode.CO2;
+            }
+            if (state.dataContaminantBalance->Contaminant.GenericContamSimulation) {
+                exhNode.GenContam = zoneNode.GenContam;
+            }
+        }
+    }
+}
+
 } // namespace EnergyPlus::DataZoneEquipment

src/EnergyPlus/DataZoneEquipment.hh

@@ -386,6 +386,10 @@ namespace DataZoneEquipment {
         }
 
         void setTotalInletFlows(EnergyPlusData &state);
+
+        void beginEnvirnInit(EnergyPlusData &state);
+
+        void hvacTimeStepInit(EnergyPlusData &state, bool FirstHVACIteration);
     };
 
     struct EquipmentData // data for an individual component