Allow GPU-based shading calculations

.decent_ci-MacOS.yaml

@@ -4,4 +4,4 @@ compilers:
      - IFW
      - TGZ
     release_build_cmake_extra_flags: -DBUILD_DOCS:BOOL=ON
-    cmake_extra_flags: -DBUILD_FORTRAN=ON -DBUILD_PACKAGE:BOOL=ON -DBUILD_TESTING:BOOL=ON -DENABLE_REGRESSION_TESTING:BOOL=ON -DREGRESSION_BASELINE_PATH:PATH=$REGRESSION_BASELINE -DREGRESSION_SCRIPT_PATH:PATH=$REGRESSION_DIR -DREGRESSION_BASELINE_SHA:STRING=$REGRESSION_BASELINE_SHA -DCOMMIT_SHA=$COMMIT_SHA -DENABLE_GTEST_DEBUG_MODE:BOOL=OFF
+    cmake_extra_flags: -DBUILD_FORTRAN=ON -DBUILD_PACKAGE:BOOL=ON -DBUILD_TESTING:BOOL=ON -DENABLE_REGRESSION_TESTING:BOOL=ON -DREGRESSION_BASELINE_PATH:PATH=$REGRESSION_BASELINE -DREGRESSION_SCRIPT_PATH:PATH=$REGRESSION_DIR -DREGRESSION_BASELINE_SHA:STRING=$REGRESSION_BASELINE_SHA -DCOMMIT_SHA=$COMMIT_SHA -DENABLE_GTEST_DEBUG_MODE:BOOL=OFF -DOPENGL_REQUIRED:BOOL=ON

.decent_ci-Windows.yaml

@@ -6,7 +6,7 @@ compilers:
     build_package_generator:
      - IFW
     release_build_cmake_extra_flags: -DBUILD_DOCS:BOOL=ON -DTEX_INTERACTION="nonstopmode"
-    cmake_extra_flags: -DBUILD_FORTRAN:BOOL=ON -DBUILD_PACKAGE:BOOL=ON -DBUILD_TESTING:BOOL=ON -DENABLE_REGRESSION_TESTING:BOOL=ON -DREGRESSION_BASELINE_PATH:PATH=%REGRESSION_BASELINE% -DREGRESSION_SCRIPT_PATH:PATH=%REGRESSION_DIR% -DREGRESSION_BASELINE_SHA:STRING=%REGRESSION_BASELINE_SHA% -DCOMMIT_SHA=%COMMIT_SHA% -DENABLE_GTEST_DEBUG_MODE:BOOL=OFF
+    cmake_extra_flags: -DBUILD_FORTRAN:BOOL=ON -DBUILD_PACKAGE:BOOL=ON -DBUILD_TESTING:BOOL=ON -DENABLE_REGRESSION_TESTING:BOOL=ON -DREGRESSION_BASELINE_PATH:PATH=%REGRESSION_BASELINE% -DREGRESSION_SCRIPT_PATH:PATH=%REGRESSION_DIR% -DREGRESSION_BASELINE_SHA:STRING=%REGRESSION_BASELINE_SHA% -DCOMMIT_SHA=%COMMIT_SHA% -DENABLE_GTEST_DEBUG_MODE:BOOL=OFF -DOPENGL_REQUIRED:BOOL=ON
 
   - name: Visual Studio
     version: 16
@@ -15,4 +15,4 @@ compilers:
      - IFW
      - ZIP
     release_build_cmake_extra_flags: -DBUILD_DOCS:BOOL=ON -DTEX_INTERACTION="nonstopmode"
-    cmake_extra_flags: -DBUILD_FORTRAN:BOOL=ON -DBUILD_PACKAGE:BOOL=ON -DBUILD_TESTING:BOOL=ON -DENABLE_REGRESSION_TESTING:BOOL=ON -DREGRESSION_BASELINE_PATH:PATH=%REGRESSION_BASELINE% -DREGRESSION_SCRIPT_PATH:PATH=%REGRESSION_DIR% -DREGRESSION_BASELINE_SHA:STRING=%REGRESSION_BASELINE_SHA% -DCOMMIT_SHA=%COMMIT_SHA% -DENABLE_GTEST_DEBUG_MODE:BOOL=OFF
+    cmake_extra_flags: -DBUILD_FORTRAN:BOOL=ON -DBUILD_PACKAGE:BOOL=ON -DBUILD_TESTING:BOOL=ON -DENABLE_REGRESSION_TESTING:BOOL=ON -DREGRESSION_BASELINE_PATH:PATH=%REGRESSION_BASELINE% -DREGRESSION_SCRIPT_PATH:PATH=%REGRESSION_DIR% -DREGRESSION_BASELINE_SHA:STRING=%REGRESSION_BASELINE_SHA% -DCOMMIT_SHA=%COMMIT_SHA% -DENABLE_GTEST_DEBUG_MODE:BOOL=OFF -DOPENGL_REQUIRED:BOOL=ON

CMakeLists.txt

@@ -54,6 +54,17 @@ else()
   set(GIT_DIR "")
 endif()
 
+set( OPENGL_REQUIRED OFF CACHE BOOL "Require OpenGL in order to build" )
+if(OPENGL_REQUIRED)
+  find_package(OpenGL)
+  if(NOT OPENGL_FOUND)
+    set(CMAKE_VERSION_BUILD "${CMAKE_VERSION_BUILD} (No OpenGL)" CACHE STRING "Build number" FORCE) # git sha
+    message(WARNING "OpenGL libraries were not found. EnergyPlus will be compiled without GPU acceleration capabilities.")
+  endif()
+else()
+  set( OPENGL_FOUND FALSE )
+endif()
+
 # Set a default build type if none was specified
 if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
   message(STATUS "Setting build type to 'Release' as none was specified.")
@@ -147,6 +158,9 @@ INCLUDE_DIRECTORIES( ${CMAKE_SOURCE_DIR}/third_party/SQLite/ SYSTEM )
 INCLUDE_DIRECTORIES( "${CMAKE_SOURCE_DIR}/third_party/Expat" "${CMAKE_SOURCE_DIR}/third_party/Expat/lib" SYSTEM )
 INCLUDE_DIRECTORIES( ${CMAKE_SOURCE_DIR}/third_party/CLI/ )
 INCLUDE_DIRECTORIES( ${CMAKE_SOURCE_DIR}/third_party/eigen/ )
+if( OPENGL_FOUND )
+  INCLUDE_DIRECTORIES( ${CMAKE_SOURCE_DIR}/third_party/penumbra/include )
+endif()
 INCLUDE_DIRECTORIES( ${CMAKE_SOURCE_DIR}/third_party/Windows-CalcEngine/src/Chromogenics/include)
 INCLUDE_DIRECTORIES( ${CMAKE_SOURCE_DIR}/third_party/Windows-CalcEngine/src/Common/include)
 INCLUDE_DIRECTORIES( ${CMAKE_SOURCE_DIR}/third_party/Windows-CalcEngine/src/Gases/include)
@@ -162,6 +176,11 @@ INCLUDE_DIRECTORIES( ${CMAKE_SOURCE_DIR}/third_party/Windows-CalcEngine/src/View
 
 set(RE2_BUILD_TESTING OFF CACHE BOOL "" FORCE)
 
+
+if( OPENGL_FOUND )
+  set(BUILD_PENUMBRA_TESTING ${BUILD_TESTING} CACHE BOOL "" FORCE)
+endif()
+
 if( BUILD_TESTING )
   set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
   set(BUILD_GTEST ON CACHE BOOL "" FORCE)
@@ -199,6 +218,10 @@ ADD_SUBDIRECTORY(third_party/btwxt)
 # Kiva
 INCLUDE(third_party/cmake/kiva.cmake)
 
+if( OPENGL_FOUND )
+  ADD_SUBDIRECTORY(third_party/penumbra)
+endif()
+
 execute_process( COMMAND ${PYTHON_EXECUTABLE} "${CMAKE_SOURCE_DIR}/scripts/dev/generate_epJSON_schema/generate_epJSON_schema.py" "${CMAKE_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}")

cmake/CompilerFlags.cmake

@@ -3,6 +3,10 @@
 ADD_CXX_DEFINITIONS("-DOBJEXXFCL_ALIGN=64") # Align ObjexxFCL arrays to 64B
 ADD_CXX_DEBUG_DEFINITIONS("-DOBJEXXFCL_ARRAY_INIT_DEBUG") # Initialize ObjexxFCL arrays to aid debugging
 
+if (NOT OPENGL_FOUND)
+  add_definitions("-DEP_NO_OPENGL")
+endif()
+
 # Make sure expat is compiled as a static library
 ADD_DEFINITIONS("-DXML_STATIC")
 

design/FY2019/GPU-Shading.md

@@ -0,0 +1,54 @@
+GPU-based Shading Calculations
+==============================
+
+**Neal Kruis, Big Ladder Software, LLC**
+
+## Justification for New Feature ##
+
+GPU architecture is optimized for performing geometry operations. Leveraging methodologies used in the gaming industry to represent shadows, the GPU can (in theory) improve computational performance of shading calculations and provide greater flexibility (e.g., handle concave geometries and solar transmission through interior glazing).
+
+## Approach ##
+
+The general approach is to use the Pixel Counting methodology described by Jones et al. In this approach, the building is rendered using OpenGL. Each surface is then viewed from the (parallel projection) perspective of the sun. The number of visible pixels for that surface is a proxy for the projected sunlit surface area. Dividing by the cosign of incidence for that surface gives the total sunlit surface area.
+
+### Exterior Shading ###
+
+Pixel counting for exterior shading can be handled using Big Ladder's [Penumbra](https://github.com/bigladder/penumbra) library (a C++ implementation of Jones's pixel counting method).
+
+### Interior Solar Distribution ###
+
+We will count pixels when viewing the from the perspective of the sun through a window with each internal surface assigned a different color, then use the histogramming functions in OpenGL to report the number of pixels of each color that are visible. This functionality will be added to Penumbra.
+
+### Pitfalls ###
+
+#### Hardware requirements ####
+
+This approach only works if there are graphics drivers (or emulators) that support OpenGL version 2.1 (or higher) on the machine running the code. This introduces a new hardware requirement for EnergyPlus. If GPU-based shading is requested and the required hardware (or emulated hardware) is not present, EnergyPlus will issue a warning and revert to the CPU-based polygon clipping method.
+
+#### Transparent shading surfaces ####
+
+Non-opaque shading surfaces are difficult to characterize under this approach (although, from early testing of SolarShadingTest.idf it doesn't appear to be working properly with the CPU calculations either).
+
+There are a couple potential solutions to this problem:
+
+1. We use the perforated approach described by Jones.
+2. We introduce transparency to the OpenGL rendering and calculate the color of the pixels returned.
+3. We render with and without transparent surfaces to evaluate their impact.
+
+## Input Output Reference Documentation ##
+
+See proposed changes in [Energy+.idd.in](https://github.com/NREL/EnergyPlus/pull/7302/files#diff-23ccf090b80d26e885712256b9a6d888). Will draft document once IDD is reviewed.
+
+## Engineering Reference ##
+
+Mainly a reference to Jones's papers.
+
+## References ##
+
+[Fast computer graphics techniques for calculating direct solar radiation on complex building surfaces](http://dx.doi.org/10.1080/19401493.2011.582154)
+
+Nathaniel L. Jones, Donald P. Greenberg, and Kevin B. Pratt. Journal of Building Performance Simulation. Volume 5, Issue 5, Pages 300-312. June 26, 2011.
+
+[Hardware accelerated computation of direct solar radiation through transparent shades and screens](https://nljones.github.io/publications/SB12_TS09b_3_Jones.pdf)
+
+Nathaniel L. Jones and Donald P. Greenberg. 5th National Conference of the International Building Performance Simulation Association-USA. Madison, Wisconsin. August 1-3, 2012

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

@@ -2,11 +2,7 @@ \section{Shading Module}\label{shading-module}
 
 \subsection{Shading and Sunlit Area Calculations}\label{shading-and-sunlit-area-calculations}
 
-When assessing heat gains in buildings due to solar radiation, it is necessary to know how much of each part of the building is shaded and how much is in direct sunlight. As an example, the figure below shows a flat roofed, L-shaped structure with a window in each of the visible sides. The sun is to the right so that walls 1 and 3 and windows a and c are completely shaded, and wall 4 and window d are completely sunlit. Wall 2 and window b are partially shaded. The sunlit area of each surface changes as the position of the sun changes during the day. The purpose of the EnergyPlus shadow algorithm is to compute these \textbf{sunlit areas}.~ Predecessors to the EnergyPlus shadowing concepts include the BLAST and TARP shadowing algorithms.
-
-The shadow algorithm is based on coordinate transformation methods similar to Groth and Lokmanhekim and the shadow overlap method of Walton.
-
-Using the \textbf{ShadowCalculation} object, you can set how often the shadowing calculations are performed. Calculating them every timestep (TimestepFrequency options) is obviously the most accurate but is also be the most time consuming.~ Using a greater length of time (number of days) before calculating again can yield speedier results.~ For lengths of time greater than one day, the solar position values (e.g.~equation of time, sun position angles) are averaged over that time period for the shadowing calculations. For dynamic shading, TimestepFrequency is required to capture changes in shading transmittance.
+When assessing heat gains in buildings due to solar radiation, it is necessary to know how much of each part of the building is shaded and how much is in direct sunlight. As an example, the figure below shows a flat roofed, L-shaped structure with a window in each of the visible sides. The sun is to the right so that walls 1 and 3 and windows a and c are completely shaded, and wall 4 and window d are completely sunlit. Wall 2 and window b are partially shaded. The sunlit area of each surface changes as the position of the sun changes during the day. The purpose of the EnergyPlus shadow algorithms is to compute these \textbf{sunlit areas}.~ Predecessors to the EnergyPlus shadowing concepts include the BLAST and TARP shadowing algorithms.
 
 \begin{figure}[hbtp] % fig 38
 \centering
@@ -73,10 +69,6 @@ \subsection{Surface Geometry}\label{surface-geometry}
 
 Collinear -- points that essentially form a ``line'' rather than a surface shape.
 
-Resolution of 1mm or less -- near collinear points.
-
-Note that the resolution on surfaces/shadowing is 1 mm -- using resolution beyond that will result in truncation of the shadowing.
-
 \begin{figure}[hbtp] % fig 40
 \centering
 \includegraphics[width=0.9\textwidth, height=0.9\textheight, keepaspectratio=true]{media/image605.png}
@@ -174,6 +166,19 @@ \subsubsection{World Coordinates to Relative Coordinates}\label{world-coordinate
 
 \subsection{Shadow Projection}\label{shadow-projection}
 
+Using the \textbf{ShadowCalculation} object, you can set how often the shadowing calculations are performed. Calculating them every timestep (Timestep frequency option) is obviously the most accurate but is also be the most time consuming.~ Using a greater length of time (number of days) before calculating again can yield speedier results.~ For lengths of time greater than one day, the solar position values (e.g.~equation of time, sun position angles) are averaged over that time period for the shadowing calculations. For dynamic shading, Timestep frequency is required to capture changes in shading transmittance.
+
+EnergyPlus provides four methods for calculating sunlit fractions:
+
+\begin{enumerate}
+    \item Polygon Clipping: The shadow algorithm is based on coordinate transformation methods similar to Groth and Lokmanhekim and the shadow overlap method of Walton.
+    \item Pixel Counting: GPU-rendering based calculations based on the method developed by Jones et al 2011.
+    \item Scheduled: Pre-calculated sunlit fractions are input through a schedule in the \textbf{\hyperref[surfacePropertylocalEnvironment]{SurfaceProperty:LocalEnvironment}} object.
+    \item Imported: Pre-calculated sunlit fractions are input through a \textbf{\hyperref[schedulefileshading]{Schedule:File:Shading}} object.
+\end{enumerate}
+
+The remaining description in this section describes the Polygon Clipping method. For information on the Pixel Counting method, refer to Jones et al 2011.
+
 All architectural forms are represented by plane polygons. This can give good accuracy even for curved surfaces: a sphere can be approximated by the 20 nodes of an icosahedron with only 3 percent error in the shadow area cast by the sphere. Consider how a solid object, which is composed of a set of enclosing plane polygons, casts a shadow. Figure~\ref{fig:basic-shadowing-concept-structure} shows a box shaped structure on a horizontal surface. The structure consists of a top (surface 1) and four vertical surfaces (2 and 3 visible to the observer and 4 and 5 not visible). The sun is positioned behind and to the right of the structure and a shadow is cast onto the horizontal surface (the ground).
 
 Surfaces 1, 4, and 5 are in sunlight; 2 and 3 are in shade. It is possible to think of the structure's shadow as the combination of shadows cast by surfaces 1, 2, 3, 4 and 5 or by 1, 4 and 5, or by surfaces 2 and 3.~ This last combination of shadow casting surfaces is the simplest. In the EnergyPlus shadow algorithm every surface is considered to be one of the surfaces that enclose a solid, and only those surfaces that are not sunlit at a given hour are considered shadowing surfaces.
@@ -240,6 +245,8 @@ \subsection{Shadow Projection}\label{shadow-projection}
 
 More explicitly, a casting surface -- a shadow casting surface or general casting surface -- is one that casts a shadow on other surfaces. A receiving surface -- a shadow receiving surface -- is one that receives shadows from other surfaces (i.e.~casting surfaces). A back surface -- an inside surface -- is one that may be partially sunlit/receive solar transmission for interior solar distribution.
 
+Note that the resolution on surfaces/shadowing is 1 mm -- using resolution beyond that will result in truncation of the shadowing.
+
 \subsection{Homogeneous Coordinates}\label{homogeneous-coordinates}
 
 Two-dimensional homogeneous coordinate techniques are used to determine the vertices of shadow overlaps. In homogeneous coordinates, points and lines are represented by a single form that allows simple vector operations between those forms {[}Newman-Sproul{]}.~ A point (X, Y) is represented by a three element vector (x, y, w) where x = w*X, y = w*Y, and w is any real number except zero. A line is also represented by a three element vector (a, b, c). The directed line (a, b, c) from point (x\(_{1}\), y\(_{1}\), w\(_{1}\)) to point (x\(_{2}\), y\(_{2}\), w\(_{2}\)) is given by:
@@ -789,6 +796,8 @@ \subsection{References}\label{references-041}
 
 Zhang, Qingyuan, Joe Huang, and Siwei Lang. 2002. ``Development of Typical Year Weather Data for Chinese Locations'', American Society of Heating Refrigeration and Air-Conditioning Engineers, ASHRAE Transactions, Vol 108, Part 2.
 
+Jones N., Greenberg D., Pratt K. ``Fast computer graphics techniques for calculating direct solar radiation on complex building surfaces''. Journal of Building Performance Simulation. Volume 5, Issue 5, Pages 300-312. June 26, 2011.
+
 Threlkeld, J.L. and R.C. Jordan. 1958. Direct solar radiation available on clear days. ASHRAE Transactions 64:45.
 
 Groth, C. C., and Lokmanhekim, M. 1969. ``Shadow ‑ A New Technique for the Calculation of Shadow Shapes and Areas by Digital Computer,'' Second Hawaii International Conference on System Sciences, Honolulu, HI, January 22‑24, 1969.