Merge remote-tracking branch 'upstream/develop' into array1s-removal

.decent_ci-Linux.yaml

@@ -5,7 +5,7 @@ compilers:
      - "STGZ"
      - "TGZ"
     release_build_cmake_extra_flags: -DENABLE_REGRESSION_TESTING:BOOL=ON -DBUILD_DOCS:BOOL=ON
-    cmake_extra_flags: -DBUILD_DOCS:BOOL=ON -DTEX_INTERACTION="nonstopmode" -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 -DBUILD_PERFORMANCE_TESTS:BOOL=ON -DVALGRIND_ANALYZE_PERFORMANCE_TESTS:BOOL=ON
+    cmake_extra_flags: -DLINK_WITH_PYTHON=ON -DBUILD_DOCS:BOOL=ON -DTEX_INTERACTION="nonstopmode" -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 -DBUILD_PERFORMANCE_TESTS:BOOL=ON -DVALGRIND_ANALYZE_PERFORMANCE_TESTS:BOOL=ON
     collect_performance_results: true
     s3_upload: doc-pdf
     s3_upload_bucket: energyplus
@@ -31,7 +31,7 @@ compilers:
     version: "7.4"
     build_type: Debug
     build_package_generator: "STGZ"
-    cmake_extra_flags: -DBUILD_FORTRAN=ON -DBUILD_TESTING:BOOL=ON -DENABLE_REGRESSION_TESTING:BOOL=OFF -DCOMMIT_SHA=$COMMIT_SHA -DENABLE_COVERAGE:BOOL=ON -DENABLE_GTEST_DEBUG_MODE:BOOL=OFF
+    cmake_extra_flags: -DLINK_WITH_PYTHON=ON -DBUILD_FORTRAN=ON -DBUILD_TESTING:BOOL=ON -DENABLE_REGRESSION_TESTING:BOOL=OFF -DCOMMIT_SHA=$COMMIT_SHA -DENABLE_COVERAGE:BOOL=ON -DENABLE_GTEST_DEBUG_MODE:BOOL=OFF
     coverage_enabled: true
     coverage_base_dir: src/EnergyPlus
     coverage_pass_limit: 41.0
@@ -46,7 +46,7 @@ compilers:
     version: "7.4"
     build_type: Debug
     build_package_generator: "STGZ"
-    cmake_extra_flags: -DBUILD_FORTRAN=ON -DBUILD_TESTING:BOOL=ON -DENABLE_REGRESSION_TESTING:BOOL=OFF -DCOMMIT_SHA=$COMMIT_SHA -DENABLE_COVERAGE:BOOL=ON -DENABLE_GTEST_DEBUG_MODE:BOOL=OFF
+    cmake_extra_flags: -DLINK_WITH_PYTHON=ON -DBUILD_FORTRAN=ON -DBUILD_TESTING:BOOL=ON -DENABLE_REGRESSION_TESTING:BOOL=OFF -DCOMMIT_SHA=$COMMIT_SHA -DENABLE_COVERAGE:BOOL=ON -DENABLE_GTEST_DEBUG_MODE:BOOL=OFF
     coverage_enabled: true
     coverage_base_dir: src/EnergyPlus
     coverage_pass_limit: 68.0

.decent_ci-MacOS.yaml

@@ -4,4 +4,5 @@ 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 -DLINK_WITH_PYTHON=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,5 @@ 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 -DLINK_WITH_PYTHON=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.")
@@ -76,7 +87,7 @@ option( ENABLE_INSTALL_REMOTE "Enable install_remote and install_remote_plist co
 
 mark_as_advanced( ENABLE_INSTALL_REMOTE )
 
-# we are making python a required dependency, so find it here
+# we are making *a Python 3 Interpreter* a required dependency, so find it here
 find_package(PythonInterp 3 REQUIRED)
 
 if( BUILD_TESTING )
@@ -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")
 

cmake/PythonCopyStandardLib.py

@@ -0,0 +1,45 @@
+# Copies the Python standard library to the target dir
+# If the target_dir already exists, it doesn't do anything
+# an easy way is to find the __init__ file for a known standard lib package and go two parents up
+# should result in something like `/usr/lib/python3.7`
+
+# this script must be called with a target directory to copy this into
+import ctypes
+from distutils.dir_util import copy_tree
+import os
+import platform
+import shutil
+import sys
+
+if len(sys.argv) == 3:
+    exe_path = sys.argv[1]
+    folder_name = sys.argv[2]
+else:
+    print("Must call " + sys.argv[0] + "with two command line arguments: the path to the energyplus exe and the name "
+                                       "of the new library directory")
+    sys.exit(1)
+exe_dir = os.path.dirname(exe_path)
+target_dir = os.path.join(exe_dir, folder_name)
+if os.path.exists(target_dir):
+    sys.exit(0)
+
+ctypes_import_file = os.path.abspath(ctypes.__file__)
+ctypes_package_dir = os.path.dirname(ctypes_import_file)
+standard_lib_dir = os.path.dirname(ctypes_package_dir)
+shutil.copytree(standard_lib_dir, target_dir)
+
+# On Windows, we also need to grab the DLLs folder, which is one folder up
+if platform.system() == 'Windows':
+    python_root_dir = os.path.dirname(standard_lib_dir)
+    dll_dir = os.path.join(python_root_dir, 'DLLs')
+    copy_tree(dll_dir, target_dir)
+
+# then I'm going to try to clean up any __pycache__ folders in the target dir to reduce installer size
+for root, dirs, _ in os.walk(target_dir):
+    for this_dir in dirs:
+        if this_dir == "__pycache__":
+            shutil.rmtree(os.path.join(root, this_dir))
+
+# on Windows the site_packages folder is inside the standard lib folder, so we need to delete that too
+if os.path.exists(os.path.join(target_dir, 'site-packages')):
+    shutil.rmtree(os.path.join(target_dir, 'site-packages'))

cmake/PythonFixUpOnMac.cmake

@@ -0,0 +1,39 @@
+# Only call this for APPLE
+# set RESOLVED_PYTHON_LIB, and EXECUTABLE_PATH when calling
+
+message("Fixing up Python Dependencies on Mac")
+
+# get some path info things
+get_filename_component(BASE_PATH ${EXECUTABLE_PATH} DIRECTORY)
+get_filename_component(PYTHON_LIB_FILENAME ${RESOLVED_PYTHON_LIB} NAME)
+
+# initialize this
+set(EPLUS_LIB_NAME "")
+
+# on Mac, we then need to fixup the binary
+include(GetPrerequisites)
+get_prerequisites("${EXECUTABLE_PATH}" PREREQUISITES 1 1 "" "")
+foreach(PREREQ IN LISTS PREREQUISITES)
+  string(TOLOWER "${PREREQ}" PREREQ_LOWERCASE )
+  string(FIND "${PREREQ_LOWERCASE}" "python" PYTHON_IN_PREREQ)
+  string(FIND "${PREREQ_LOWERCASE}" "libenergyplusapi" EPLUS_IN_PREREQ)
+  if (NOT EPLUS_IN_PREREQ EQUAL -1)
+    get_filename_component(EPLUS_LIB_NAME ${PREREQ} NAME)
+  endif()
+  if (NOT PYTHON_IN_PREREQ EQUAL -1)
+    gp_resolve_item("" "${PREREQ}" "" "${LIBRARY_SEARCH_DIRECTORY}" resolved_item_var)
+    execute_process(COMMAND "install_name_tool" -change "${PREREQ}" "@executable_path/${PYTHON_LIB_FILENAME}" "${EXECUTABLE_PATH}")
+  endif()
+endforeach()
+
+# Now, I know there are better ways, but for now I'm just going to repeat it for the eplus api lib as well
+set(EPLUS_LIB_PATH "${BASE_PATH}/${EPLUS_LIB_NAME}")
+get_prerequisites("${EPLUS_LIB_PATH}" PREREQUISITES 1 1 "" "")
+foreach(PREREQ IN LISTS PREREQUISITES)
+  string(TOLOWER "${PREREQ}" PREREQ_LOWERCASE )
+  string(FIND "${PREREQ_LOWERCASE}" "python" PYTHON_IN_PREREQ)
+  if (NOT PYTHON_IN_PREREQ EQUAL -1)
+    gp_resolve_item("" "${PREREQ}" "" "${LIBRARY_SEARCH_DIRECTORY}" resolved_item_var)
+    execute_process(COMMAND "install_name_tool" -change "${PREREQ}" "@executable_path/${PYTHON_LIB_FILENAME}" "${EPLUS_LIB_PATH}")
+  endif()
+endforeach()

cmake/PythonGetBitSize.py

@@ -0,0 +1,4 @@
+# this file helps identify the Python bit size (32 or 64)
+# this is important when linking E+ against the Python library
+import struct
+print(8 * struct.calcsize("P"), end="")

cmake/PythonGetLibAndLinkUp.cmake

@@ -0,0 +1,43 @@
+# Linking up to Python is not necessarily complex, but it is tricky to get right.
+# Our goal here is to provide a fully packaged embedded Python interpreter and Python 3.5+ standard library
+# This file's job is to copy over the required Python DLL and fixup the EnergyPlus binary on Mac to find on it locally
+# To accomplish this, we need to know which EnergyPlus binary to fixup, and some info about the Python library
+# The steps we follow are:
+#  Use finder to get Python library and include paths
+#  Add Python include path to include_directories
+#  Link E+ against Python library
+#  At install time find the Python library and copy it into the install tree
+#  At install time find the Python site-packages folder and copy it into the install tree
+#  In E+ need to setPath before calling PyInitialize so we can get all the site_packages
+# Now we should also consider whether we want to try to build *without* Python
+#  I can imagine doing this on the 32 bit Windows, for example.
+#  And this would *not* exclude calling E+ as a library from C or Python -- it would just disable Python Plugins
+#  If we don't do this then we'll need to install both 32 and 64 bit Python on Windows and get the right one
+
+# We need to connect up to python for a couple reasons.
+# 1. We use Python in our testing scripts
+# 2. We link EnergyPlus up against the Python lib for Python Plugin work
+# 3. We use Python for our Python API runs
+# We are going to create a local virtual environment that is portable so we can package it and install it
+# Users will not need to have Python installed, and it will come with a Python.exe and a Pip.exe for installing libraries
+
+# set RESOLVED_PYTHON_LIB, and EXECUTABLE_PATH when calling
+
+message("Collecting Python dynamic library")
+
+# get some path info things
+get_filename_component(BASE_PATH ${EXECUTABLE_PATH} DIRECTORY)
+get_filename_component(PYTHON_LIB_FILENAME ${RESOLVED_PYTHON_LIB} NAME)
+
+# on Windows, RESOLVED_PYTHON_LIB is pointing to the likes of `C:\Python38\libs\python38.lib`,
+# when we actually want the DLL at `C:\Python38\python38.dll`
+# need to fix that up here
+if(WIN32)
+  get_filename_component(LIB_SUB_DIR "${RESOLVED_PYTHON_LIB}" DIRECTORY)
+  get_filename_component(PYTHON_ROOT_DIR "${LIB_SUB_DIR}" DIRECTORY)
+  string(REPLACE ".lib" ".dll" DLL_FILE_NAME "${PYTHON_LIB_FILENAME}")
+  set(RESOLVED_PYTHON_LIB "${PYTHON_ROOT_DIR}/${DLL_FILE_NAME}")
+endif()
+
+# then copy the DLL in
+execute_process(COMMAND "${CMAKE_COMMAND}" -E copy "${RESOLVED_PYTHON_LIB}" "${BASE_PATH}")

cmake/PythonSetupAPIinBuild.cmake

@@ -0,0 +1,23 @@
+# Sets up the pyenergyplus Python package, which is the EnergyPlus Python API wrapper, in the build tree, next to E+
+# set REPO_ROOT, EXECUTABLE_PATH (path to energyplus.exe), and E+ and API major/minor/etc version variables when calling
+
+# get the parent path of the current EXE and drop the pyenergyplus stuff in there
+get_filename_component(EPLUS_EXE_DIR ${EXECUTABLE_PATH} DIRECTORY)
+
+# informative messaging
+message("Setting up Python API, creating pyenergyplus package at ${EPLUS_EXE_DIR}/pyenergyplus")
+
+# now do it
+if (NOT EXISTS "${EPLUS_EXE_DIR}/pyenergyplus")
+    file(MAKE_DIRECTORY "${EPLUS_EXE_DIR}/pyenergyplus")
+endif()
+set(API_SOURCE_DIR "${REPO_ROOT}/src/EnergyPlus/api")
+set(API_TARGET_DIR "${EPLUS_EXE_DIR}/pyenergyplus")
+configure_file( "${API_SOURCE_DIR}/common.py" "${API_TARGET_DIR}/common.py" )
+configure_file( "${API_SOURCE_DIR}/datatransfer.py" "${API_TARGET_DIR}/datatransfer.py" )
+configure_file( "${API_SOURCE_DIR}/api.py" "${API_TARGET_DIR}/api.py" )
+configure_file( "${API_SOURCE_DIR}/func.py" "${API_TARGET_DIR}/func.py" )
+configure_file( "${API_SOURCE_DIR}/datatransfer.py" "${API_TARGET_DIR}/datatransfer.py" )
+configure_file( "${API_SOURCE_DIR}/runtime.py" "${API_TARGET_DIR}/runtime.py" )
+configure_file( "${API_SOURCE_DIR}/plugin.py" "${API_TARGET_DIR}/plugin.py" )
+configure_file( "${API_SOURCE_DIR}/__init__.py" "${API_TARGET_DIR}/__init__.py" )

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