Merge remote-tracking branch 'upstream/develop' into Fix_7136_PeakCoil

cmake/CompilerFlags.cmake

@@ -255,3 +255,10 @@ if("Ninja" STREQUAL ${CMAKE_GENERATOR})
   endif()
 endif()
 
+# Xcode/Ninja generators undefined MAKE
+if(CMAKE_GENERATOR MATCHES "Make")
+  set(MAKE "$(MAKE)")
+else()
+  set(MAKE make)
+endif()
+

cmake/Install.cmake

@@ -149,7 +149,7 @@ if( WIN32 AND NOT UNIX )
   set(CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP TRUE)
   include(InstallRequiredSystemLibraries)
   if(CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS)
-  install(PROGRAMS ${CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS} DESTINATION "./")
+    install(PROGRAMS ${CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS} DESTINATION "./")
   endif()
 endif()
 
@@ -443,7 +443,7 @@ elseif(WIN32)
   # You need at least one "install(..." command for it to be registered as a component
   install(CODE "MESSAGE(\"Registering filetypes.\")" COMPONENT RegisterFileType)
   install(CODE "MESSAGE(\"Copying and Registering DLLs\")" COMPONENT CopyAndRegisterSystemDLLs)
-
+  install(CODE "MESSAGE(\"Creating start menu.\")" COMPONENT CreateStartMenu)
 
 endif()
 
@@ -482,6 +482,44 @@ set(CPACK_PROJECT_CONFIG_FILE "${CMAKE_BINARY_DIR}/CMakeCPackOptions.cmake")
 ##########################################################   D O C U M E N T A T I O N   #############################################################
 
 if ( BUILD_DOCS )
+  # Call the build of target documentation explicitly here.
+  # Note: This is because you can't do `add_dependencies(package documentation)` (https://gitlab.kitware.com/cmake/cmake/issues/8438)
+  # Adding another custom target to be added to the "ALL" one (so it runs) and make it depend on the actual "documentation" target doesn't work
+  # because it'll always run if you have enabled BUILD_DOCS, regardless of whether you are calling the target "package" or not
+  #  add_custom_target(run_documentation ALL)
+  #  add_dependencies(run_documentation documentation)
+  #message(FATAL_ERROR "CMAKE_COMMAND=${CMAKE_COMMAND}")
+
+  # +env will pass the current environment and will end up respecting the -j parameter
+  #                                 this ↓↓↓ here -- https://stackoverflow.com/a/41268443/531179
+  #install(CODE "execute_process(COMMAND +env \"${CMAKE_COMMAND}\" --build \"${CMAKE_BINARY_DIR}\" --target documentation)")
+  # Except it doesn't work with install(execute_process...
+
+  # Passing $(MAKE) doesn't work either, and isn't a great idea for cross platform support anyways
+  # install(CODE "execute_process(COMMAND ${MAKE} ${DOC_BUILD_FLAGS} -C \"${CMAKE_BINARY_DIR}\" documentation)")
+
+  # So instead, we just used the number of threads that are available. That's not ideal, since it ignores any "-j N" option passed by the user
+  # But LaTeX should run quickly enough to not be a major inconvenience.
+  # There no need to do that for Ninja for eg, so only do it for Make and MSVC
+
+  # flag -j to cmake --build was added at 3.12 (VERSION_GREATER_EQUAL need cmake >= 3.7, we apparently support 2.8...)
+  if(NOT(CMAKE_VERSION VERSION_LESS "3.12") AND ((CMAKE_GENERATOR MATCHES "Make") OR WIN32))
+    include(ProcessorCount)
+    ProcessorCount(N)
+    if(NOT N EQUAL 0)
+      set(DOC_BUILD_FLAGS "-j ${N}")
+    endif()
+  endif()
+  if(WIN32)
+    # Win32 is multi config, so you must specify a config when calling cmake.
+    # Let's just use Release, it won't have any effect on LaTeX anyways.
+    set(DOC_CONFIG_FLAG "--config Release")
+  endif()
+
+  # Getting these commands to work (especially with macro expansion) is tricky. Check the resulting `cmake_install.cmake` file in your build folder if need to debug this
+  install(CODE "execute_process(COMMAND \"${CMAKE_COMMAND}\" --build \"${CMAKE_BINARY_DIR}\" ${DOC_CONFIG_FLAG} ${DOC_BUILD_FLAGS} --target documentation)"
+          COMPONENT Documentation)
+
   install(FILES "${CMAKE_BINARY_DIR}/doc-pdf/Acknowledgments.pdf" DESTINATION "./Documentation" COMPONENT Documentation)
   install(FILES "${CMAKE_BINARY_DIR}/doc-pdf/AuxiliaryPrograms.pdf" DESTINATION "./Documentation" COMPONENT Documentation)
   install(FILES "${CMAKE_BINARY_DIR}/doc-pdf/EMSApplicationGuide.pdf" DESTINATION "./Documentation" COMPONENT Documentation)
@@ -496,9 +534,11 @@ if ( BUILD_DOCS )
   install(FILES "${CMAKE_BINARY_DIR}/doc-pdf/PlantApplicationGuide.pdf" DESTINATION "./Documentation" COMPONENT Documentation)
   install(FILES "${CMAKE_BINARY_DIR}/doc-pdf/TipsAndTricksUsingEnergyPlus.pdf" DESTINATION "./Documentation" COMPONENT Documentation)
   install(FILES "${CMAKE_BINARY_DIR}/doc-pdf/UsingEnergyPlusForCompliance.pdf" DESTINATION "./Documentation" COMPONENT Documentation)
+else()
+  message(AUTHOR_WARNING "BUILD_DOCS isn't enabled, so package won't include the PDFs")
 endif ()
 
-##########################################################   S Y S T E M    L I B R A R I E S   #############################################################
+##########################################################   S Y S T E M    L I B R A R I E S   ######################################################
 
 # TODO: is this unecessary now? I had forgotten to actually create a Libraries via cpack_add_component but everything seemed fined
 # At worse, try not to uncomment this as is, but place it inside an if(PLATFORM) statement
@@ -559,6 +599,12 @@ cpack_add_component(Licenses
   DESCRIPTION "License files for EnergyPlus"
   REQUIRED)
 
+# No need for system privileges for this
+cpack_add_component(CreateStartMenu
+  DISPLAY_NAME "Start Menu links"
+  DESCRIPTION "Create Start Menu Links"
+)
+
 cpack_add_component(RegisterFileType
   DISPLAY_NAME "Associate with EP-Launch and IDFEditor"
   DESCRIPTION "Associate *.idf, *.imf, and *.epg files with EP-Launch, *.ddy and *.expidf with IDFEditor.exe"
@@ -585,6 +631,10 @@ cpack_ifw_configure_component(Symlinks
     REQUIRES_ADMIN_RIGHTS
 )
 
+cpack_ifw_configure_component(CreateStartMenu
+    SCRIPT cmake/qtifw/install_win_createstartmenu.qs
+)
+
 cpack_ifw_configure_component(RegisterFileType
     SCRIPT cmake/qtifw/install_registerfiletype.qs
     REQUIRES_ADMIN_RIGHTS

cmake/qtifw/install_operations.qs

@@ -27,18 +27,7 @@ function Component()
     // On Windows
     if( kernel == "winnt" ) {
 
-      // Create Shortcuts in the Windows Start Menu
-      component.addOperation("CreateShortcut", "@TargetDir@/Documentation/index.html", "@StartMenuDir@/EnergyPlus Documentation.lnk");
-      component.addOperation("CreateShortcut", "@TargetDir@/PostProcess/EP-Compare/EP-Compare.exe", "@StartMenuDir@/EP-Compare.lnk");
-      component.addOperation("CreateShortcut", "@TargetDir@/PreProcess/EPDraw/EPDrawGUI.exe", "@StartMenuDir@/EPDrawGUI.lnk");
-      component.addOperation("CreateShortcut", "@TargetDir@/EP-Launch.exe", "@StartMenuDir@/EP-Launch.lnk");
-      component.addOperation("CreateShortcut", "@TargetDir@/ExampleFiles/ExampleFiles.html", "@StartMenuDir@/Example Files Summary.lnk");
-      component.addOperation("CreateShortcut", "@TargetDir@/ExampleFiles/ExampleFiles-ObjectsLink.html", "@StartMenuDir@/ExampleFiles Link to Objects.lnk");
-      component.addOperation("CreateShortcut", "@TargetDir@/PreProcess/IDFEditor/IDFEditor.exe", "@StartMenuDir@/IDFEditor.lnk");
-      component.addOperation("CreateShortcut", "@TargetDir@/PreProcess/IDFVersionUpdater/IDFVersionUpdater.exe", "@StartMenuDir@/IDFVersionUpdater.lnk");
-      component.addOperation("CreateShortcut", "@TargetDir@/readme.html", "@StartMenuDir@/Readme Notes.lnk");
-      component.addOperation("CreateShortcut", "@TargetDir@/PreProcess/WeatherConverter/Weather.exe", "@StartMenuDir@/Weather Statistics and Conversions.lnk");
-
+      // Create Shortcuts in the Windows Start Menu: done separately (optional)
 
       // Note: Associate file types: done separately (optional)
 

cmake/qtifw/install_win_createstartmenu.qs

@@ -0,0 +1,29 @@
+// Windows commands to be performed elevated: copy and register DLLs
+
+function Component()
+{
+  Component.prototype.createOperations = function()
+  {
+    // call default implementation
+    component.createOperations();
+
+    // ... add custom operations
+
+    var kernel = systemInfo.kernelType;
+    // On Windows
+    if( kernel == "winnt" ) {
+
+      component.addOperation("CreateShortcut", "@TargetDir@/Documentation/index.html", "@StartMenuDir@/EnergyPlus Documentation.lnk");
+      component.addOperation("CreateShortcut", "@TargetDir@/PostProcess/EP-Compare/EP-Compare.exe", "@StartMenuDir@/EP-Compare.lnk");
+      component.addOperation("CreateShortcut", "@TargetDir@/PreProcess/EPDraw/EPDrawGUI.exe", "@StartMenuDir@/EPDrawGUI.lnk");
+      component.addOperation("CreateShortcut", "@TargetDir@/EP-Launch.exe", "@StartMenuDir@/EP-Launch.lnk");
+      component.addOperation("CreateShortcut", "@TargetDir@/ExampleFiles/ExampleFiles.html", "@StartMenuDir@/Example Files Summary.lnk");
+      component.addOperation("CreateShortcut", "@TargetDir@/ExampleFiles/ExampleFiles-ObjectsLink.html", "@StartMenuDir@/ExampleFiles Link to Objects.lnk");
+      component.addOperation("CreateShortcut", "@TargetDir@/PreProcess/IDFEditor/IDFEditor.exe", "@StartMenuDir@/IDFEditor.lnk");
+      component.addOperation("CreateShortcut", "@TargetDir@/PreProcess/IDFVersionUpdater/IDFVersionUpdater.exe", "@StartMenuDir@/IDFVersionUpdater.lnk");
+      component.addOperation("CreateShortcut", "@TargetDir@/readme.html", "@StartMenuDir@/Readme Notes.lnk");
+      component.addOperation("CreateShortcut", "@TargetDir@/PreProcess/WeatherConverter/Weather.exe", "@StartMenuDir@/Weather Statistics and Conversions.lnk");
+
+    }
+  }
+}

doc/CMakeLists.txt

@@ -7,6 +7,9 @@ file(COPY ${CMAKE_SOURCE_DIR}/doc/index.html DESTINATION ${CMAKE_BINARY_DIR}/doc
 # add a configure rule to the header file though
 configure_file(${CMAKE_SOURCE_DIR}/doc/title.tex.in ${CMAKE_SOURCE_DIR}/doc/title.tex)
 
+# Because we don't want to rebuild doc automatically, we add a custom target called "documentation", which will depends on all individual PDFs
+add_custom_target(documentation)
+
 # add each of the documents, they have their own CMakeLists.txt files
 add_subdirectory(acknowledgments)
 add_subdirectory(auxiliary-programs)

doc/acknowledgments/CMakeLists.txt

@@ -24,6 +24,9 @@ add_custom_command( OUTPUT ${CMAKE_BINARY_DIR}/doc/${OUTPUT_FILENAME}.pdf
 		    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/doc/${SOURCE_FILENAME}
 		    DEPENDS ${INCLUDED_TEX} ${INCLUDED_IMAGES}
                  )
-add_custom_target( zPDF_${OUTPUT_FILENAME} ALL
+add_custom_target( zPDF_${OUTPUT_FILENAME}
                    DEPENDS ${CMAKE_BINARY_DIR}/doc/${OUTPUT_FILENAME}.pdf
                  )
+
+# Make top-level 'documentation' target depend on this one
+add_dependencies(documentation zPDF_${OUTPUT_FILENAME})

doc/auxiliary-programs/CMakeLists.txt

@@ -200,6 +200,9 @@ add_custom_command( OUTPUT ${CMAKE_BINARY_DIR}/doc/${OUTPUT_FILENAME}.pdf
 		    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/doc/${SOURCE_FILENAME}
 		    DEPENDS ${INCLUDED_TEX} ${INCLUDED_IMAGES}
                  )
-add_custom_target( zPDF_${OUTPUT_FILENAME} ALL
+add_custom_target( zPDF_${OUTPUT_FILENAME}
                    DEPENDS ${CMAKE_BINARY_DIR}/doc/${OUTPUT_FILENAME}.pdf
                  )
+
+# Make top-level 'documentation' target depend on this one
+add_dependencies(documentation zPDF_${OUTPUT_FILENAME})

doc/ems-application-guide/CMakeLists.txt

@@ -90,6 +90,9 @@ add_custom_command( OUTPUT ${CMAKE_BINARY_DIR}/doc/${OUTPUT_FILENAME}.pdf
 		    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/doc/${SOURCE_FILENAME}
 		    DEPENDS ${INCLUDED_TEX} ${INCLUDED_IMAGES}
                  )
-add_custom_target( zPDF_${OUTPUT_FILENAME} ALL
+add_custom_target( zPDF_${OUTPUT_FILENAME}
                    DEPENDS ${CMAKE_BINARY_DIR}/doc/${OUTPUT_FILENAME}.pdf
                  )
+
+# Make top-level 'documentation' target depend on this one
+add_dependencies(documentation zPDF_${OUTPUT_FILENAME})

doc/engineering-reference/CMakeLists.txt

@@ -541,6 +541,9 @@ add_custom_command( OUTPUT ${CMAKE_BINARY_DIR}/doc/${OUTPUT_FILENAME}.pdf
 		    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/doc/${SOURCE_FILENAME}
 		    DEPENDS ${INCLUDED_TEX} ${INCLUDED_IMAGES}
                  )
-add_custom_target( zPDF_${OUTPUT_FILENAME} ALL
+add_custom_target( zPDF_${OUTPUT_FILENAME}
                    DEPENDS ${CMAKE_BINARY_DIR}/doc/${OUTPUT_FILENAME}.pdf
                  )
+
+# Make top-level 'documentation' target depend on this one
+add_dependencies(documentation zPDF_${OUTPUT_FILENAME})

doc/engineering-reference/src/simulation-models-encyclopedic-reference-002/evaporative-coolers.tex

@@ -411,7 +411,7 @@ \subsubsection{Secondary Air Flow Fraction}\label{secondary-air-flow-fraction}
 ff_{sec} = \frac{\dot{m}_{sec}}{\dot{m}_{sec,design}}
 \end{equation}
 
-The secondary air mass flow rate will either be set to or solved for numerically as described below. The secondary side flow fraction, , is defined as. (Note this is another flow ratio that differs from the one used above which combined both streams into one ratio in effectiveness modifier curves.)
+And secondary air fan electric power \(p_{sec,fan}\) is calculated as.
 
 \begin{equation}
 P_{sec,fan} = P_{sec,fan,design}\cdot f_{sec,fan,mod}\left(ff_{sec}\right)
@@ -525,13 +525,13 @@ \subsubsection{Secondary Air Flow Fraction}\label{secondary-air-flow-fraction}
 PLF = \frac{{{{\dot Q}_{{\mathop{\rm Re}\nolimits} quired}}}}{{{{\dot Q}_{Full}}}}
 \end{equation}
 
-where \(PLF\) is the Part Load Fraction.~ When PLF is less than 1.0, it is assumed that the cooler will deliver the desired temperature air (as long as it is less than the inlet; it doesn't need heating).~ The PLF is used to modify the auxiliary fan power when the fan power modifier curve is not specified and find when the unit will overcool.
+where \(PLF\) is the Part Load Fraction.~ When PLF is less than 1.0, it is assumed that the cooler will deliver the desired temperature air (as long as it is less than the inlet; it doesn't need heating).~ The PLF is used along with secondary side flow fraction to modify the auxiliary fan power when the fan power modifier curve is not specified and find when the unit will overcool.
 
 \begin{equation}
-{P_{fan}} = \Delta P\cdot \dot V\cdot e\cdot PLF
+{P_{fan}} = \Delta P\cdot \dot V\cdot e\cdot PLF\cdot ff_{sec}
 \end{equation}
 
-Water pump power is also derated using the PLF.
+Water pump power is also derated using the PLF and \(ff_{sec}\).
 
 A third air stream input to the cooler was implemented in order to allow mixing building exhaust air with outdoor air on the purge/secondary side of the cooler. The assumption when relief/tertiary air is used is that all of the available relief zone air is used and the remainder made up with outdoor air.~ Moisture and energy balances are drawn to compute humidity ratio and enthalpy of mixed secondary air.~ The volume is determined by the design volume flow rate (from secondary fan size).
 
@@ -658,7 +658,7 @@ \subsection{Direct Evaporative Cooler Special Research Model}\label{direct-evapo
 
 The wetbulb temperature of air leaving a direct cooler is the same as the wetbulb temperature entering the cooler.~ The leaving humidity ratio of the air is calculated using psychrometric functions with leaving drybulb and wetbulb temperatures and outdoor air pressure as inputs.~ The leaving enthalpy of air is calculated using psychrometric functions with leaving drybulb temperature, leaving humidity ratio, and outdoor air pressure as inputs.
 
-The direct cooler sometimes has the ability to overcool the air and therefore some form of modulation is useful for analysis.~ The special research model includes a Part Load Fraction, PLF, used to model the implications of controlling the amount of cooling.~ It is assumed that through some sort of on/off cycling or wetness control that the cooling electric power can be varied to exactly meet the desired temperature when PLF is less than unity.~ The auxiliary water pump power is then varied using pump power modifier curve or linearly using a Part Load Fraction when the pump power modifier curve is not specified.
+The direct cooler sometimes has the ability to overcool the air and therefore some form of modulation is useful for analysis.~ The special research model includes a Part Load Fraction, PLF, used to model the implications of controlling the amount of cooling.~ It is assumed that through some sort of on/off cycling or wetness control that the cooling electric power can be varied to exactly meet the desired temperature when PLF is less than unity.~ The auxiliary water pump power is then derated using user specified pump power modifier curve or linearly using a Part Load Fraction and a fan flow fraction when the pump power modifier curve is not specified.
 
 \begin{equation}
 {\rm{FullOutput}} = {T_{db,out}} - {T_{db,in}}
@@ -675,7 +675,6 @@ \subsection{Direct Evaporative Cooler Special Research Model}\label{direct-evapo
 \label{eq:IECPLF}
 \end{equation}
 
-When PLF is less than 1.0 it is assumed that the cooler will deliver the desired temperature air (as long as it is less than the inlet; it doesn't need heating).~ Water pump power is also derated using the user specified pump modifier curve or using PLF when the pump modifier curve is not specified.
 
 \subsubsection{Water Consumption}\label{water-consumption-1}