Merge branch 'develop' into MultispeedFans

.gitignore

@@ -48,9 +48,6 @@ testfiles/*.htm
 # this is autogenerated in the src dir
 doc/title.tex
 
-# ignore Energy+.schema.epJSON while it is auto-generated from IDD
-Energy+.schema.epJSON.in
-
 # ignore the doxygen and sphinx built API docs
 doc/readthedocs/doxygen/_build
 doc/readthedocs/sphinx/_build
@@ -88,3 +85,7 @@ CMakeSettings.json
 
 # py2app puts things inside dist/ and build/, build/ is already ignored, just add dist/
 dist
+
+# if you generate sphinx docs, it builds a dummy version of the schema in the idd folder, just ignore it
+/idd/Energy+.schema.epJSON
+/idd/Energy+.schema.epJSON.in

CMakeLists.txt

@@ -298,15 +298,6 @@ endif()
 # E+ required libraries
 add_subdirectory(idd)
 
-execute_process(
-  COMMAND ${Python_EXECUTABLE} "${PROJECT_SOURCE_DIR}/scripts/dev/generate_epJSON_schema/generate_epJSON_schema.py" "${PROJECT_SOURCE_DIR}"
-  TIMEOUT 30
-  RESULT_VARIABLE generate_epJSON_schema_result)
-if(${generate_epJSON_schema_result} MATCHES ".*timeout.*")
-  message(FATAL_ERROR "Generating epJSON Schema from IDD failed: ${generate_epJSON_schema_result}")
-endif()
-configure_file(idd/Energy+.idd.in "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/Energy+.idd")
-configure_file(idd/Energy+.schema.epJSON.in "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/Energy+.schema.epJSON")
 configure_file(idd/BasementGHT.idd "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/BasementGHT.idd")
 configure_file(idd/SlabGHT.idd "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/SlabGHT.idd")
 
@@ -322,7 +313,6 @@ configure_file("workflows/transition.py" "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/work
 # of course E+ itself
 add_subdirectory(src/EnergyPlus)
 set_target_properties(airflownetworklib PROPERTIES FOLDER "Internal")
-set_target_properties(GenerateEmbeddedEpJSONSchema PROPERTIES FOLDER "Internal")
 set_target_properties(energyplusparser PROPERTIES FOLDER "Internal")
 
 if(BUILD_TESTING)

design/FY2023/NFP-evapCoolerRHcontrol.md

@@ -0,0 +1,153 @@
+
+Enhancement of Evaporative Cooler in EnergyPlus
+================
+
+**Yujie Xu, Tianzhen Hong**
+
+**Lawrence Berkeley National Laboratory***
+
+ - Original Date: Apr 7, 2023
+ - Modified Date: Apr 11, 2023
+
+## Justification for Feature Update
+
+As global climate change continues, the frequency, duration and intensity of heatwaves could increase. As an affordable and energy efficient cooling option [1], evaporative cooling could become more prevalent in the future, especially in hot and dry climates. As a result, it is crucial to provide accurate and more user-friendly simulation support for prototyping new evaporative coolers and their applications. With this motivation, this EnergyPlus feature is proposed to provide an additional relative humidity-driven control option.
+
+![zoneEvapCoolerDiagram](zoneEvapCoolerDiagram.png)
+<p style="text-align: center;"> Figure 1. Conceptual diagram of a direct evaporative cooler [source](https://basc.pnnl.gov/resource-guides/evaporative-cooling-systems#edit-group-description) (left), an example of a zone-level direct evaporative cooler[source](https://www.nytimes.com/wirecutter/blog/do-swamp-coolers-work/) (right).</p>
+
+The enhancement was motivated by discussions with the CBE research group at UC Berkeley: Hui Zhang, Roberto Rugani, and Maria Andre.
+
+## Overview ##
+
+The introduction of excessive moisture is one of the potential issues of direct evaporative coolers. A humidity control could become useful in preventing the evaporative cooler from raising indoor humidity to an uncomfortable level. Currently, the direct evaporative cooler can be controlled with the sensor node temperature using AvailabilityManagers (*AvailabilityManager:LowTemperatureTurnOff* or *AvailabilityManager:HighTemperatureTurnOn*). This feature proposes to add a relative humidity (RH) control to shut down the evaporative cooler when the indoor relative humidity is too high.
+
+We plan to enhance the zone level evaporative cooler object, *ZoneHVAC:EvaporativeCoolerUnit*. This is a compound object that combines a fan and one
+Each evaporative cooler in this object can be a direct or indirect. This feature will add some additional fields to this zone-level object, allowing user to specify a relative-humidity threshold above which the unit will be turned off.
+
+## Approach
+
+To enable a high-relative-humidity-cutoff control, a field will be added to the *ZoneHVAC:EvaporativeCoolerUnit* object. See Section IDD object change for details.
+
+## Testing/Validation/Data Source(s)
+
+This feature will be tested and demonstrated with a test file derived from StripMallZoneEvapCooler.idf. Manual check of the time-step EnergyPlus simulation results will be conducted to confirm the added feature is working correctly. 
+
+## IDD Object changes
+
+A field (N4) will be added to the ZoneHVAC:EvaporativeCoolerUnit
+
+    ZoneHVAC:EvaporativeCoolerUnit,
+        \memo Zone evaporative cooler. Forced-convection cooling-only unit with supply fan,
+        \memo 100% outdoor air supply. Optional relief exhaust node
+        \min-fields 15
+    A1 , \field Name
+        \required-field
+        \reference ZoneEquipmentNames
+    A2 , \field Availability Schedule Name
+        \note Availability schedule name for this system. Schedule value > 0 means the system is available.
+        \note If this field is blank, the system is always available.
+        \type object-list
+        \object-list ScheduleNames
+    A3,  \field Availability Manager List Name
+        \note Enter the name of an AvailabilityManagerAssignmentList object.
+        \type object-list
+        \object-list SystemAvailabilityManagerLists
+    A4 , \field Outdoor Air Inlet Node Name
+        \required-field
+        \type node
+        \note this is an outdoor air node
+    A5 , \field Cooler Outlet Node Name
+        \required-field
+        \type node
+        \note this is a zone inlet node
+    A6 , \field Zone Relief Air Node Name
+        \type node
+        \note this is a zone exhaust node, optional if flow is being balanced elsewhere
+    A7 , \field Supply Air Fan Object Type
+        \required-field
+        \type choice
+        \key Fan:SystemModel
+        \key Fan:ComponentModel
+        \key Fan:ConstantVolume
+        \key Fan:OnOff
+        \key Fan:VariableVolume
+    A8 , \field Supply Air Fan Name
+        \required-field
+        \type object-list
+        \object-list Fans
+    N1 , \field Design Supply Air Flow Rate
+        \required-field
+        \units m3/s
+        \minimum> 0
+        \autosizable
+    A9 , \field Fan Placement
+        \required-field
+        \type choice
+        \key BlowThrough
+        \key DrawThrough
+    A10, \field Cooler Unit Control Method
+        \required-field
+        \type choice
+        \key ZoneTemperatureDeadbandOnOffCycling
+        \key ZoneCoolingLoadOnOffCycling
+        \key ZoneCoolingLoadVariableSpeedFan
+    N2 , \field Throttling Range Temperature Difference
+        \note used for ZoneTemperatureDeadbandOnOffCycling hystersis range for thermostatic control
+        \type real
+        \units deltaC
+        \default 1.0
+        \minimum> 0.0
+    N3 , \field Cooling Load Control Threshold Heat Transfer Rate
+        \type real
+        \units W
+        \default 100.0
+        \note Sign convention is that positive values indicate a cooling load
+        \minimum> 0.0
+    A11, \field First Evaporative Cooler Object Type
+        \required-field
+        \type choice
+        \key EvaporativeCooler:Direct:CelDekPad
+        \key EvaporativeCooler:Direct:ResearchSpecial
+        \key EvaporativeCooler:Indirect:CelDekPad
+        \key EvaporativeCooler:Indirect:WetCoil
+        \key EvaporativeCooler:Indirect:ResearchSpecial
+    A12, \field First Evaporative Cooler Object Name
+        \required-field
+        \type object-list
+        \object-list EvapCoolerNames
+    A13, \field Second Evaporative Cooler Object Type
+        \note optional, used for direct/indirect configurations
+        \note second cooler must be immediately downstream of first cooler, if present
+        \type choice
+        \key EvaporativeCooler:Direct:CelDekPad
+        \key EvaporativeCooler:Direct:ResearchSpecial
+        \key EvaporativeCooler:Indirect:CelDekPad
+        \key EvaporativeCooler:Indirect:WetCoil
+        \key EvaporativeCooler:Indirect:ResearchSpecial
+    A14, \field Second Evaporative Cooler Name
+        \note optional, used for direct/indirect configurations
+        \type object-list
+        \object-list EvapCoolerNames
+    A15, \field Design Specification ZoneHVAC Sizing Object Name
+        \note Enter the name of a DesignSpecificationZoneHVACSizing object.
+        \type object-list
+        \object-list DesignSpecificationZoneHVACSizingName
+    N4; \field Shut Off Relative Humidity
+        \note Zone relative humidity above which the evap cooler is shut off.
+        \type real
+        \minimum 0.00
+        \maximum 100.00
+        \units percent
+
+## Proposed additions to Meters:
+
+N/A
+
+## Proposed Report Variables:
+
+N/A
+
+## References
+
+[1] https://www.energy.gov/energysaver/evaporative-coolers <br>

doc/engineering-reference/src/climate-sky-and-solar-shading-calculations/shading-module.tex

@@ -406,39 +406,93 @@ \subsubsection{Overlapping Shadows}\label{overlapping-shadows}
 \caption{Complex Overlapping Condition \protect \label{fig:complex-overlapping-condition}}
 \end{figure}
 
-If two shadows overlap the receiving surface, they may also overlap each other as in Figure~\ref{fig:multiple-shadow-overlaps}. The vertices of this overlap can be computed.~ The areas of all overlaps can be computed.~ The total sunlit area can be expressed as the sum of all polygon areas given a proper sign on each of the areas.
+If two shadows overlap the receiving surface, they may also overlap each other as in Figure~\ref{fig:multiple-shadow-overlaps}. The vertices of this overlap can be computed, and the areas of all overlaps can be computed. For opaque shadows, the total sunlit area can be expressed as the sum of all polygon areas using the sign convention shown in Table \ref{table:surface-area-characteristic-convention}:
 
-The following convention was adopted:
+\begin{equation}
+SunlitArea = {\sum\limits_{i = 1}^n {A_i}}
+\end{equation}
 
-% table 24
-\begin{longtable}[c]{@{}ll@{}}
-\caption{Surface / Area Characteristic / Convention \label{table:surface-area-characteristic-convention}} \tabularnewline
+Each shadow's area is subtracted from the receiving surface and so on through multiple overlaps where the sign of the overlap area is the product of the signs of the overlapping areas. For the shadows in Figure~\ref{fig:multiple-shadow-overlaps}, start with the receiving surface area A, subtract shadow area B, then subtract shadow area C. Because shadows B and C overlap, the overlap area D has been subtracted twice, so add back area D to get the final sunlit area on the receiving surface.
+
+
+\begin{longtable}[c]{>{\raggedright}p{2.9in}p{1.5in}p{1.59in}}
+\caption{Overlapping Shadow Surface Area Convention \label{table:surface-area-characteristic-convention}} \tabularnewline
 \toprule
-Surface Characteristic & Area Convention \tabularnewline
+Surface Characteristic & Area Convention & Sunlit Area \tabularnewline
 \midrule
 \endfirsthead
 
-\caption[]{Surface / Area Characteristic / Convention} \tabularnewline
+\caption[]{Overlapping Shadow Surface Area Convention} \tabularnewline
 \toprule
-Surface Characteristic & Area Convention \tabularnewline
+Surface Characteristic & Area Convention & Sunlit Area \tabularnewline
 \midrule
 \endhead
 
-receiving surface & positive (A) \tabularnewline
-overlap between shadow and receiving & negative (B  \&  C) \tabularnewline
-overlap between two shadows & positive (D) \tabularnewline
+receiving surface & positive A & A \tabularnewline
+overlap between shadow and receiving & negative B & A-B \tabularnewline
+overlap between shadow and receiving & negative C & A-B-C \tabularnewline
+overlap between two shadows & positive D & A-B-C+D \tabularnewline
 \bottomrule
 \end{longtable}
 
-and so on through multiple overlaps where the sign of the overlap area is the product of the signs of the overlapping areas.
-
 \begin{figure}[hbtp] % fig 47
 \centering
 \includegraphics[width=0.9\textwidth, height=0.9\textheight, keepaspectratio=true]{media/image642.png}
 \caption{Multiple Shadow Overlaps \protect \label{fig:multiple-shadow-overlaps}}
 \end{figure}
 
-Partially transparent shadowing surfaces can also be modeled by giving a transparency ($\tau$) to every shadowing polygon. Let $\tau$ of the receiving polygon be one. Then the $\tau$ of every overlap of polygons i and j is the product of $\tau$\(_{i}\)and $\tau$\(_{j}\). The shaded area is then computed by summing A\(_{i}\)*(1 - $\tau$\(_{i}\)) for all overlap polygons.
+Partially transparent shadowing surfaces can also be modeled by giving a transparency ($\tau$) to every shadowing polygon. The sunlit area is computed by:
+
+\begin{equation}
+SunlitArea = A_1 + {\sum\limits_{i = 2}^n {A_i}*(1-\tau_i)}
+\end{equation}
+
+The actual $\tau$ of overlapping polygons i and j is the product of $\tau_i$ and $\tau_j$. For example, if a wall is fully shaded by two partially transparent shades, one with a transmittance of 0.8 and one with a transmittance of 0.5, the resulting sunlit fraction would be $0.8 * 0.5 = 0.4$. Because each shadow is first applied with its own transmittance, the ``transmittance'' for the overlap correction ($\tau_k$) in the sunlit area summation is derived from the individual surface transmittance values:
+
+\begin{equation}
+\tau_k = (\tau_{i} + \tau_{j}) - (\tau_{i} * \tau_{j})
+\end{equation}
+
+where $\tau_k$ is the correction ``transmittance''  for the shadow overlap area (D in Figure~\ref{fig:multiple-shadow-overlaps}).
+
+For example, using the overlapping shadows in Figure~\ref{fig:multiple-shadow-overlaps}, the sunlit area can be calculated two ways as shown in Table~\ref{table:sunlit-area-calculation-overlapping-shadows}. Method 1 avoids any overlaps by calculating adjusted areas. Method 2 uses the EnergyPlus summation approach and shows the transmittance correction calculation for the overlap area to arrive at the same result. Stepping through Method 2: start with the full surface area A, subtract the shaded area $B*(1-\tau_b)$, subtract the shaded area $C*(1-\tau_c)$. At this point, the overlapping area D has been subtracted twice, once using $\tau_b$ and once using $\tau_c$. To correct for this, area D is added back in with the adjusted ``transmittance'' using the equation shown above for $\tau_k$. Once the sunlit area is known for each surface, the sunlit fraction is calculated, which is $13.56/20=0.678$ for this example.
+
+\begin{longtable}[c]{>{\raggedright}p{1.2in}p{1.5in}p{2.0in}p{2.0in}}
+\caption{Sunlit Area Calculations with Overlapping Partially Transmitting Shadows\label{table:sunlit-area-calculation-overlapping-shadows}} \tabularnewline
+\toprule
+Region & Area & Transmittance & Sunlit Area \tabularnewline
+\midrule
+\endfirsthead
+
+\caption[]{Sunlit Area Calculations with Overlapping Partially Transmitting Shadows} \tabularnewline
+\toprule
+Region & Area & Transmittance & Sunlit Area \tabularnewline
+\midrule
+\endhead
+
+Assumptions: \tabularnewline
+A & 20 & 1.0 \tabularnewline
+B & 10 & 0.8 \tabularnewline
+C & 8 & 0.4 \tabularnewline
+D & 3 &  \tabularnewline
+\midrule
+Method 1 & Adjusted Areas:\tabularnewline
+$A-B-C+D$ & $20-10-8+3 = 5$ & $1.0$               & $5*1.0 = 5.00$ \tabularnewline
+$B-D$     & $10-3=7$        & $0.8$               & $7*0.8 = 5.60$ \tabularnewline
+$C-D$     & $8-3=5$         & $0.4$               & $5*0.4 = 2.00$ \tabularnewline
+$D$       & $3$             & $0.8 * 0.4 = 0.32$  & $3*0.32 = 0.96$ \tabularnewline
+Total     & $20$            &                     & $13.56$ \tabularnewline
+\midrule
+Method 2 & Full Areas:\tabularnewline
+$A$   & $20$         & n/a                             & $20.00$ \tabularnewline
+$B$   & $-10$        & $0.8$                           & $-10*(1-0.8) = -2.00$ \tabularnewline
+$C$   & $-8$         & $0.4$                           & $-8*(1-0.4) = -4.80$ \tabularnewline
+$D$   & $3$          & $(0.8+0.4)-(0.8 * 0.4) = 0.88$  & $+3*(1-0.88) = 0.36$ \tabularnewline
+Total &              &                                 & $13.56$ \tabularnewline
+\bottomrule
+\end{longtable}
+
+
 
 It is easy to determine the sunlit area of a window once all the shadow and overlap vertices on the wall have been computed. Consider wall 2 of Figure~\ref{fig:overall-shadowing-scheme-depiction}. First, the wall is considered a simple rectangle and the window on it is ignored. The shadow overlapping is performed and the sunlit portion of the gross wall area is computed. Then the window rectangle is overlapped with the shadow to determine its sunlit area. The sunlit area of the window is subtracted from the gross wall sunlit area to determine the net wall sunlit area. During this calculation it is not necessary to recompute the shadows, because they were precisely determined on the wall.
 

doc/input-output-reference/src/overview/group-zone-forced-air-units.tex

@@ -1547,6 +1547,12 @@ \subsubsection{Inputs}\label{inputs-4-040}
 
 This optional input field is the name of a \hyperref[designspecificationzonehvacsizing]{DesignSpecification:ZoneHVAC:Sizing} object. The name must correspond to unique name of a \hyperref[designspecificationzonehvacsizing]{DesignSpecification:ZoneHVAC:Sizing} object defined elsewhere. A Design Sepcification Zone HVAC Sizing object defines scalable sizing methods for sizing input field \emph{Design Supply Air Flow Rate} in Evaportaive Cooler zone HVAC object. The scaled design supply air flow rates in turn is used to size capacity of the unit.
 
+\paragraph{Field: Shut Off Relative Humidity}\label{shut-off-relative-humidity}
+
+This is an optional field. When the relative humidity of the zone is above this
+threshold, the evaporative cooler is shut off. This intends to prevent direct
+evaporative coolers from adding too much moisture into the zone.
+
 An example input object follows.
 
 \begin{lstlisting}

doc/readthedocs/sphinx/conf.py

@@ -134,15 +134,15 @@
 # # OK, now we need to make sure the epJSON schema is generated so we can process it
 # Since this will primarily just be run by readthedocs, I'm just going to re-run the schema generator
 try:
-    check_call(['python3', 'scripts/dev/generate_epJSON_schema/generate_epJSON_schema.py', '.'], cwd=repo_root)
+    check_call(['python3', 'scripts/dev/generate_epJSON_schema/generate_epJSON_schema.py', 'idd'], cwd=repo_root)
 except CalledProcessError as e:
     raise Exception(f"Schema Generation failed! Exception string: {str(e)}") from None
 except FileNotFoundError as e:
     raise Exception(
         f"python3 binary not found, what?  Looked for it at: `python3'; error = {str(e)}"
     ) from None
 
-generated_schema_file = repo_root / 'idd' / 'Energy+.schema.epJSON.in'  # I know this will have CMake placeholders
+generated_schema_file = repo_root / 'idd' / 'Energy+.schema.epJSON'  # I know this will have CMake placeholders
 if not generated_schema_file.exists():
     raise Exception("Generated schema file did not exist, aborting.")
 print("* Generated schema existence confirmed")