Use local nodes for air flow network calculation

doc/engineering-reference/src/surface-heat-balance-manager-processes/outside-surface-heat-balance.tex

@@ -153,6 +153,17 @@ \subsection{External Longwave Radiation}\label{external-longwave-radiation}
 {h_{r,air}} = \frac{{\varepsilon \sigma {F_{sky}}\left( {1 - \beta } \right)(T_{surf}^4 - T_{air}^4)}}{{{T_{surf}} - {T_{air}}}}
 \end{equation}
 
+Optionally, however, the long wave radiation from surrounding surfaces to an exterior surface, can also be considered if explicitly defined. Then the equation above should be modified as:
+\begin{equation}
+q_{_{LWR}}^`` = \varepsilon \sigma[{F_{gnd}}(T_{gnd}^4 - T_{surf}^4) + {F_{sky}}(T_{sky}^4 - T_{surf}^4)  + {F_{s_1}}(T_{s_1}^4 - T_{surf}^4)+ ... + {F_{s_n}}(T_{s_n}^4 - T_{surf}^4) +  {F_{air}}(T_{air}^4 - T_{surf}^4)]
+\end{equation}
+
+where
+
+F\(_{s_i}\) = View factor of surrounding surface i to the exterior surface.
+
+T\(_{s_i}\) = Outside surface temperature of the surrounding surface i.
+
 \subsection{References}\label{references-034}
 
 ASHRAE. 1993. 1993 ASHRAE Handbook -- Fundamentals. Atlanta: American Society of Heating, Refrigerating, and Air-Conditioning Engineers, Inc.

doc/input-output-reference/src/overview/group-advanced-surface-concepts.tex

@@ -2506,6 +2506,127 @@ \subsubsection{Inputs}\label{inputs-16}
 
 This field specifies the aspect ratio that the building described in the rest of the input file will be changed to.
 
+\subsection{SurfaceProperty:SurroundingSurfaces}\label{surfacePropertysurroundingSurfaces}
+
+The object is used to calculate long wave radiation to an external surface from its surrounding surfaces, defining the properties of the surrounding surfaces. The property object declares a list of single surrounding surfaces which has a name, a field of view factor, and another field Temperature Schedule Name referencing a schedule containing the temperature of the surrounding surface, which can be overwritten at each time step in EnergyPlus run time through co-simulation. View factors are assumed to be constant values. At least one surrounding surface should be defined in this object.
+
+The object also defines the sky and ground temperature and view factors to the external surface. The sum of all defined view factors should not exceed 1.0. If only sky view is defined in this object, the ground view factor to this surface will be 1.0 subtracted with the ground view factor and all other defined surface view factors. If only ground view is defined in this object, the sky view factor to this surface will be 1.0 subtracted with the sky view factor and all other defined surface view factors. If neither of the sky and ground view factors are explicitly declared here, the sum of the sky and ground view factor would be 1.0 subtracted with all other defined surface view factors and the proportion will be set as the same with the global setting. 
+
+\subsubsection{Field: Name}\label{field-srd-surfs-name}
+
+This is the unique name of the surface property.
+
+\subsubsection{Field: Sky View Factor}\label{field-sky-view-factor}
+
+This field defines the constant sky view factor to an external surface. The sky view factor used in solar radiation calculation of the surface would be overwritten with the value of the fraction if defined here. If the field is left blank, the sky view factor of this surface will be calculated with the rules demonstrated above.
+
+\subsubsection{Field: Sky Temperature Schedule Name}\label{field-sky-temperature-schedule-name}
+
+This field is used to supply a schedule name of the sky temperature. The sky temperature used in solar radiation calculation of the surface would be overwritten with the value of the scheduled temperature if defined here. If the field is left blank, the global sky temperature would be used.
+
+\subsubsection{Field: Ground View Factor}\label{field-ground-view-factor}
+
+This field defines the constant ground view factor to an external surface. The ground view factor used in solar radiation calculation of the surface would be overwritten with the value of the fraction if defined here. If the field is left blank, the ground view factor of this surface will be calculated with the rules demonstrated above.
+
+\subsubsection{Field: Ground Temperature Schedule Name}\label{field-ground-temperature-schedule-name}
+
+This field is used to supply a schedule name of the ground temperature. The ground temperature used in solar radiation calculation of the surface would be overwritten with the value of the scheduled temperature if defined here. If the field is left blank, the global ground temperature would be used.
+
+\subsubsection{Field: Surrounding Surface 1 Name}\label{field-surrounding-surface-1-name}
+
+This field defines the name of a surrounding surface to the external surface. 
+
+\subsubsection{Field: Surrounding Surface 1 View Factor}\label{field-surrounding-surface-1-view-factor}
+
+This field defines the constant view factor of a surrounding surface to an external surface. 
+
+\subsubsection{Field: Surrounding Surface 1 Temperature Schedule Name}\label{field-surrounding-surface-1-temp-schedule-name}
+
+This field is used to supply a schedule name of the of a surrounding surface temperature. 
+
+The last three fields are extensible to define multiple surrounding surface name, temperature and view factor sets.
+
+An example IDF object follows.
+
+\begin{lstlisting}
+SurfaceProperty:SurroundingSurfaces,
+  SrdSurfs:Window,             !- Name
+  0.3,                         !- Sky View Factor
+  ,                            !- Sky Temperature Schedule Name
+  0.1,                         !- Ground View Factor
+  ,                            !- Ground Temperature Schedule Name
+  SurroundingSurface1,         !- Surrounding Surface 1 Name
+  0.6,                         !- Surrounding Surface 1 View Factor
+  Surrounding Temp Sch 1;      !- Surrounding Surface 1 Temperature Schedule Name
+
+Schedule:Compact,
+  Surrounding Temp Sch 1,       !- Name
+  Any Number,                   !- Schedule Type Limits Name
+  Through: 12/31,               !- Field 1
+  For: AllDays,                 !- Field 2
+  Until: 24:00, 15.0;           !- Field 3  
+\end{lstlisting}
+
+\subsection{SurfaceProperty:LocalEnvironment}\label{surfacePropertylocalEnvironment}
+
+The object links to a surface object \textbf{Surface:Detailed} and is used when there is a need to calculate surface level environmental data externally and import them into the simulation to override existing environmental data, including external solar shading fractions, local air velocity, temperature and humidity, and surrounding surface temperatures and view factors. The object links to three optional objects including a schedule object declared by \textbf{Field: External Shading Fraction Schedule Name}, a \textbf{SurfaceProperty:SurroundingSurfaces} object declared by \textbf{Field: Surrounding Surfaces Object Name}, and an \textbf{OutdoorAir:Node} object declared by \textbf{Field: Outdoor Air Node Name}. The object provides inputs to calculate shading, solar radiation, zone air balance and surface exterior heat balance. 
+
+\subsubsection{Field: Name}\label{field-surf-localenv-name}
+
+This is the unique name of the surface property.
+
+\subsubsection{Field: Surface Name}\label{field-surface-name}
+
+This is the name of the surface that will be assigned to use the local environmental data defined in the next three fields.  This should be a name of a surface defined elsewhere.
+
+\subsubsection{Field: External Shading Fraction Schedule Name}\label{field-external-shading-fraction-schedule-name}
+
+This field is used to import external shading fraction data from external calculation. This should be a name of a schedule object with fraction input.
+
+\subsubsection{Field: Surrounding Surfaces Object Name}\label{field-surrounding-surfaces-object-name}
+
+This field is used to import surrounding surfaces properties (temperature and view factors to the external surface) from external calculation. This should be a name of a \textbf{SurfaceProperty:SurroundingSurfaces} object.
+
+\subsubsection{Field: Outdoor Air Node Name}\label{field-outdoor-air-node-name}
+
+This field is used to import local environmental data from local outdoor air nodes, including dry and wet bulb temperature, wind speed and wind direction. This should be a name of a \textbf{OutdoorAir:Node} object.
+
+An example IDF object follows.
+
+\begin{lstlisting}
+SurfaceProperty:LocalEnvironment,
+    LocEnv:Zn001:Wall001,         !- Name
+    Zn001:Wall001,                !- Exterior Surface Name
+    ExtShadingSch:Zn001:Wall001,  !- External Shading Fraction Schedule Name
+    SrdSurf:Zn001:Wall001,        !- Surrounding Surfaces Object Name
+    OutdoorAirNode:0001;          !- Outdoor Air Node Name    
+\end{lstlisting}
+
+\subsection{ZoneProperty:LocalEnvironment}\label{ZonePropertylocalEnvironment}
+
+The object links to a \textbf{Zone} object and is used when there is a need to calculate zone level environmental data externally and import them into the simulation to override existing environmental data, including local air temperature and humidity, wind velocity and direction. links to an \textbf{OutdoorAir:Node} object declared by \textbf{Field: Outdoor Air Node Name}. The reference local outdoor air node provides ambient conditions for the calculation of infiltration and ventilation at the zone level.
+
+\subsubsection{Field: Name}\label{field-zone-localenv-name}
+
+This is the unique name of the zone property.
+
+\subsubsection{Field: Zone Name}\label{field-zone-name}
+
+This is the name of the zone that will be assigned to use the local environmental data defined in the next field. This should be a name of a surface defined elsewhere.
+
+\subsubsection{Field: Outdoor Air Node Name}\label{field-zone-outdoor-air-node-name}
+
+This field is used to import local environmental data from local outdoor air nodes, including dry and wet bulb temperature, wind speed and wind direction. This should be a name of a \textbf{OutdoorAir:Node} object.
+
+An example IDF object follows.
+
+\begin{lstlisting}
+ZoneProperty:LocalEnvironment,
+    LocEnv:Zn001,                 !- Name
+    Zn001,                        !- Exterior Surface Name
+    OutdoorAirNode:0001;          !- Outdoor Air Node Name    
+\end{lstlisting}
+
 \subsection{Zone Property View Factors}\label{zone-property-view-factors}
 
 EnergyPlus has two options for specifying the thermal radiation exchange view factors between surfaces in a zone: the approximate option and the user input option. Because the actual geometric arrangement within a zone is very complex, the approximate method of including thermal mass and other forced exchanges is more realistic than trying to come up with ``exact'' view factors. However, in some research situations it might be desirable to have control of the view factors used. For this reason, a user input mode has been included in EnergyPlus. The two modes are described in the next sections.

doc/input-output-reference/src/overview/group-air-distribution.tex

@@ -749,6 +749,24 @@ \subsection{OutdoorAir:Node}\label{outdoorairnode}
 
 \textbf{OutdoorAir:Node} and \textbf{OutdoorAir:NodeList} both set a node to outdoor air conditions. \textbf{OutdoorAir:Node} modifies the weather file conditions if a height has been specified. \textbf{OutdoorAir:NodeList} does not have a height input and always uses the weather file conditions without modification. The same node name may not be used with both of these objects.
 
+When declared in surface property objects \textbf{SurfaceProperty:LocalEnvironment}, in zone property objects \textbf{ZoneProperty:LocalEnvironment}, or as an external node in the airflow network calculation linking to a surface node \textbf{AirflowNetwork:Multizone:Surface}, the object can also be used to define local outdoor air conditions for surfaces, zones or air loop components. The local outdoor air conditions would be used in the EnergyPlus calculations for: 
+\begin{enumerate}
+\item Convection coefficients used in the exterior surface heat balance
+
+If the user declares a local surface outdoor air node to overwrite the surface level environmental data, the convection coefficients would be calculated based on the local outdoor air node data accordingly based on surface level outdoor dry-bulb temperature, humidity ratio and wind speed. 
+
+\item Zone air infiltration and simple ventilation
+
+If the user declares a local zone outdoor air node to overwrite zone level environmental data, global environmental variables used in the subroutines for infiltration and ventilation calculation, including outdoor air temperature, humidity ratio, enthalpy, wind speed and direction, would be overwritten accordingly with zone level data. 
+
+\item External air nodes used in the AirFlowNetwork
+
+When used in the airflow network for wind pressure calculation, global environmental variables used in the subroutines for wind pressure calculation, including outdoor air temperature, humidity ratio, air density, wind speed and direction, would be overwritten accordingly with local data. 
+
+\end{enumerate}
+
+When used in these cases, optional schedule inputs of local ambient air conditions, including dry-bulb temperature, wet-bulb temperature, wind velocity, and wind direction, can be defined in the optional fields. When used in the airflow network for wind pressure calculation, the wind pressure coefficient curve name and calculation details should also be defined.
+
 \subsubsection{Inputs}\label{inputs-5-001}
 
 \paragraph{Field: Name}\label{field-name-5-001}
@@ -761,25 +779,70 @@ \subsubsection{Inputs}\label{inputs-5-001}
 
 A blank entry or value less than zero indicates that the height will be ignored and the weather file conditions will be used.
 
+\paragraph{Field: Drybulb Temperature Schedule Name}\label{field-drybulb-temperature-schedule-name}
+
+This field is used to supply a schedule name of the local dry bulb temperature of this node. When the field is left blank, global values would be used in calculation.
+
+\paragraph{Field: Wetbulb Temperature Schedule Name}\label{field-wetbulb-temperature-schedule-name}
+
+This field is used to supply a schedule name of the local wet bulb temperature of this node. When the field is left blank, global values would be used in calculation.
+
+\paragraph{Field: Wind Speed Schedule Name}\label{field-wind-speed-schedule-name}
+
+This field is used to supply a schedule name of the local wind speed of this node. When the field is left blank, global values would be used in calculation.
+
+\paragraph{Field: Wind Direction Schedule Name}\label{field-wind-dir-schedule-name}
+
+This field is used to supply a schedule name of the local wind direction of this node. When the field is left blank, global values would be used in calculation.
+
+\paragraph{Field: Wind Pressure Coefficient Curve Name}\label{field-wind-pressure-coeff-curve-name}
+
+The name of a specific \textbf{AirflowNetwork:MultiZone:WindPressureCoefficientValues} object (which gives wind pressure coefficients for the façade as a function of angle of wind incident on the façade).
+
+\paragraph{Field: Symmetric Wind Pressure Coefficient Curve}\label{field-sym-windp-curve-name}
+
+This field is used to specify whether the pressure curve is symmetric or not. \textbf{Yes} for curves that should be evaluated from 0 to 180 degrees. \textbf{No} for curves that should be evaluated from 0 to 360 degrees.
+
+\paragraph{Field: Wind Angle Type}\label{field-wind-angle-type}
+
+This field is used to specify whether the angle used to compute the wind pressure coefficient is absolute or relative. \textbf{Relative} for computing the angle between the wind direction and the surface azimuth. \textbf{Absolute} for using the wind direction angle directly.
+
 An example IDF:
 
 \begin{lstlisting}
 
 OutdoorAir:Node,
-    OA Node 1;  !- Name
+  OA Node 1;  !- Name
 
-  OutdoorAir:Node,
-    Floor 10 Outdoor air Inlet Node,  !- Name
-    30.0;  !- Height Above Ground {m}
+OutdoorAir:Node,
+  Floor 10 Outdoor air Inlet Node,  !- Name
+  30.0;  !- Height Above Ground {m}
+
+OutdoorAir:Node,
+  LocalOutdoorAirNode:0001,     !- Name
+  ,                             !- Height Above Ground
+  OutdoorAirNodeDryBulb:0001,   !- Drybulb Temperature Schedule Name 
+  OutdoorAirNodeWetBulb:0001,   !- Wetbulb Temperature Schedule Name
+  OutdoorAirNodeWindSpeed:0001, !- Wind Speed Schedule Name
+  OutdoorAirNodeWindDir:0001;   !- Wind Direction Schedule Name 
+  NFacade_WPCValue,             !- Wind Pressure Coefficient Curve Name
+  No,                           !- Symmetric Wind Pressure Coefficient Curve
+  Absolute;                     !- Wind Angle Type
 \end{lstlisting}
 
 \subsection{Outdoor Air Node outputs:}\label{outdoor-air-node-outputs}
 
-The ambient dry-bulb air temperature and flow rate at the outdoor air node can be monitored using the system node output variables:
+The ambient dry-bulb, wet-bulb air temperature, wind speed and direction, and flow rate at the outdoor air node can be monitored using the system node output variables:
 
 \begin{itemize}
 \item
   HVAC,Average,System Node Temperature {[}C{]}
+\item
+  HVAC,Average,System Node Wetbulb Temperature {[}C{]}
+\item
+  HVAC,Average,System Node Wind Speed {[}m/s{]}
+\item
+  HVAC,Average,System Node Wind Direction {[}degree{]}
 \item
   HVAC,Average,System Node Mass Flow Rate {[}kg/s{]}
 \end{itemize}
@@ -794,6 +857,7 @@ \subsection{Outdoor Air Node outputs:}\label{outdoor-air-node-outputs}
   Hourly;
 \end{lstlisting}
 
+
 \subsection{OutdoorAir:NodeList}\label{outdoorairnodelist}
 
 The program needs to know which HVAC system nodes are inlets for outdoor air. Knowing this, the program can set the conditions at these nodes to the outdoor conditions at the start of each major timestep. The OutdoorAir:NodeList provides the means for specifying which nodes are outdoor air nodes.