Multiple shading controls referenced by a single subsurface

developer/doc/ReleaseNotes/OpenStudio_Release_Notes_3_1_0.md

@@ -9,7 +9,6 @@ These release notes describe version 3.1.0 of the OpenStudio SDK developed by th
 -  Installation Notes
 -  OpenStudio SDK: Changelog
 
-
 # Overview
 
 Following an important announcement related to future development of the OpenStudio Application released in September 2019 ([A Shift in BTO’s BEM Strategy: A New Future for the OpenStudio Application](https://www.openstudio.net/new-future-for-openstudio-application)), **this release marks the first installment of the separated OpenStudio SDK from the Application.**
@@ -45,6 +44,7 @@ OpenStudio 3.x now uses **Ruby 2.5.5** as the supported version (2.2.4 previousl
 
 As usual, you can refer to the **[OpenStudio Compatibility Matrix](https://github.com/NREL/OpenStudio/wiki/OpenStudio-Version-Compatibility-Matrix)** for more information.
 
+
 ## Installation Steps
 
 - Download and install OpenStudio SDK and/or [OpenStudioApplication]( depending on your needs. Select components for installation. Note that OpenStudio Application is a standalone app and does not require you to install OpenStudio SDK.
@@ -66,7 +66,14 @@ A number of API-breaking changes have been implemented in OpenStudio 3.1.0:
 * [#3960](https://github.com/NREL/OpenStudio/pull/3960) - Added support for building the C# bindings via `dotnet` CLI, including on Unix platforms.
 * [#3959](https://github.com/NREL/OpenStudio/pull/3959) - Also included some improvements in the generated C# bindings by reducing build warnings and properly exposing some types via SWIG
     * `ScheduleTypeKey` (which is normally only use by OpenStudio internals in ScheduleTypeRegistry checks) previously mapped to a `std::pair<std::string, std::string>` which was SWIGed in ruby as an Array of strings of size two, but improperly exposed in C#. It now uses a dedicated helper class with two methods `ScheduleTypeKey::className()` and `ScheduleTypeKey::scheduleDisplayName()`
-
+* [#4066](https://github.com/NREL/OpenStudio/pull/4066) - Multiple shading controls referenced by a single subsurface
+    * `SubSurface` was historically the one referencing the `ShadingControl` object. Now it's a many-to-many relationship where `ShadingControl` has an extensible 'Sub Surface Name' field, and multiple `ShadingControl` objects can reference the same `SubSurface`. This is trickling down from a change introduced in EnergyPlus version 9.4, and specifically in PR [NREL/EnergyPlus#8196](https://github.com/NREL/EnergyPlus/pull/8196)
+    * Methods in `SubSurface` have been deprecated but are kept for backward compatibility. They will be removed in a future version of OpenStudio:
+        * `shadingControl()`: prefer `shadingControls()`
+        * `setShadingControl(ShadingControl&)`: use `addShadingControl(SubSurface&)`, `addShadingControls(std::vector<SubSurface>&)` or `setShadingControls(std::vector<SubSurface>&)`
+        * `resetShadingControl()`: use `removeAllShadingControls()` instead
+    * All Shading Control Type values should now be supported. Refer to issue [#4074](https://github.com/NREL/OpenStudio/issues/4074) for more information
+    * Fields 'Glare Control Is Active', 'Type of Slat Angle Control for Blinds', 'Slat Angle Schedule Name', 'Setpoint2', and 'Multiple Surface Control Type' are now implemented as well
 
 ## Minor changes:
 

resources/model/OpenStudio.idd

@@ -5706,13 +5706,7 @@ OS:SubSurface,
        \minimum 0
        \maximum 1
        \default autocalculate
-  A7, \field Shading Control Name
-       \note enter the name of a WindowProperty:ShadingControl object
-       \note used for windows and glass doors only
-       \note If not specified, window or glass door has no shading (blind, roller shade, etc.)
-       \type object-list
-       \object-list WindowShadeControlNames
-  A8, \field Frame and Divider Name
+  A7, \field Frame and Divider Name
        \note Enter the name of a WindowProperty:FrameAndDivider object
        \note Used only for exterior windows (rectangular) and glass doors.
        \note Unused for triangular windows.
@@ -5750,7 +5744,8 @@ OS:SubSurface,
        \units m
 
 OS:ShadingControl,
-       \min-fields 4
+       \extensible:1
+       \min-fields 15
   A1 , \field Handle
        \type handle
        \required-field
@@ -5878,13 +5873,28 @@ OS:ShadingControl,
        \note Used only if Shading Type = InteriorBlind, ExteriorBlind or BetweenGlassBlind.
        \note Required if Type of Slat Angle Control for Blinds = ScheduledSlatAngle
        \note Schedule values should be degrees (0 minimum, 180 maximum)
-  N2 ; \field Setpoint 2
+  N2 , \field Setpoint 2
        \note W/m2 for solar-based controls, deg C for temperature-based controls.
        \note Used only as the second setpoint for the following two-setpoint control types:
        \note OnIfHighOutdoorAirTempAndHighSolarOnWindow, OnIfHighOutdoorAirTempAndHighHorizontalSolar,
        \note OnIfHighZoneAirTempAndHighSolarOnWindow, and OnIfHighZoneAirTempAndHighHorizontalSolar
        \type real
        \ip-units unknown
+  A12, \field Multiple Surface Control Type
+       \type choice
+       \key Sequential
+       \key Group
+       \required-field
+       \note When Sequential is used the list of fenestration surfaces are controlled individually in the order specified
+       \note When Group is used the entire list is controlled simultaneously and if glare control is needed the entire
+       \note group of window shades are deployed together a the same time
+  A13; \field Sub Surface Name 1
+       \required-field
+       \begin-extensible
+       \type object-list
+       \object-list GlazedExtSubSurfNames
+       \note When Multiple Surface Control Type is set to Sequential the shades will be deployed for the referenced surface objects in order.
+       \note When that field is set to Group the entire list is controlled simultaneously.
 
 OS:WindowProperty:FrameAndDivider,
          \memo Specifies the dimensions of a window frame, dividers, and reveal surfaces.

src/energyplus/CMakeLists.txt

@@ -542,6 +542,7 @@ set(${target_name}_src
   ReverseTranslator/ReverseTranslateWindowMaterialGlazing.cpp
   ReverseTranslator/ReverseTranslateWindowMaterialSimpleGlazingSystem.cpp
   ReverseTranslator/ReverseTranslateWindowPropertyFrameAndDivider.cpp
+  ReverseTranslator/ReverseTranslateWindowShadingControl.cpp
   ReverseTranslator/ReverseTranslateZoneAirHeatBalanceAlgorithm.cpp
   ReverseTranslator/ReverseTranslateZoneAirMassFlowConservation.cpp
   ReverseTranslator/ReverseTranslateZone.cpp
@@ -650,6 +651,7 @@ set(${target_name}_test_src
   Test/ScheduleInterval_GTest.cpp
   Test/ScheduleRuleset_GTest.cpp
   Test/SetpointManagerFollowGroundTemperature_GTest.cpp
+  Test/ShadingControl_GTest.cpp
   Test/ShadingSurface_GTest.cpp
   Test/ShadowCalculation_GTest.cpp
   Test/SimulationControl_GTest.cpp

src/energyplus/ForwardTranslator.cpp

@@ -445,6 +445,7 @@ Workspace ForwardTranslator::translateModelPrivate( model::Model & model, bool f
     }
   }
 
+  // TODO: Is this still needed?
   // ensure shading controls only reference windows in a single zone and determine control sequence number
   // DLM: ideally E+ would not need to know the zone, shading controls could work across zones
   std::vector<ShadingControl> shadingControls = model.getConcreteModelObjects<ShadingControl>();
@@ -477,7 +478,7 @@ Workspace ForwardTranslator::translateModelPrivate( model::Model & model, bool f
             thisZoneHandleSet.insert(zoneHandle);
             ShadingControl clone = shadingControl.clone(model).cast<ShadingControl>();
             // assign clone to control subSurface
-            subSurface.setShadingControl(clone);
+            clone.addSubSurface(subSurface);
             auto it = zoneHandleToShadingControlVectorMap.find(zoneHandle);
             if (it == zoneHandleToShadingControlVectorMap.end()) {
               zoneHandleToShadingControlVectorMap.insert(std::make_pair(zoneHandle, std::vector<ShadingControl>()));

src/energyplus/ForwardTranslator/ForwardTranslateShadingControl.cpp

@@ -58,7 +58,32 @@ boost::optional<IdfObject> ForwardTranslator::translateShadingControl(model::Sha
   std::vector<SubSurface> subSurfaces = modelObject.subSurfaces();
 
   if (subSurfaces.empty()) {
-    LOG(Warn, modelObject.briefDescription() << " does not control any SubSurfaces, will not be translated");
+    LOG(Warn, modelObject.briefDescription() << " does not control any SubSurfaces, it will not be translated");
+    return boost::none;
+  }
+  if (!modelObject.shadingMaterial() && !modelObject.construction()) {
+    LOG(Error, modelObject.briefDescription() << " does not have either a Shading Material or a Construction assigned, it will not be translated");
+    return boost::none;
+  }
+
+  // Read this now, since we'll use it to test if a Warn is needed
+  std::string shadingControlType = modelObject.shadingControlType();
+
+  if (modelObject.isControlTypeValueNeedingSetpoint1() && !modelObject.setpoint()) {
+    LOG(Error, modelObject.briefDescription() << " is using Shading Control Type '" << shadingControlType
+        << "' which requires a Setpoint which is missing, it will not be translated");
+    return boost::none;
+  }
+
+  if (modelObject.isControlTypeValueNeedingSetpoint2() && !modelObject.setpoint2()) {
+    LOG(Error, modelObject.briefDescription() << " is using Shading Control Type '" << shadingControlType
+        << "' which requires a Setpoint2 which is missing, it will not be translated");
+    return boost::none;
+  }
+
+  if (modelObject.isControlTypeValueRequiringSchedule() && !modelObject.schedule()) {
+    LOG(Error, modelObject.briefDescription() << " is using Shading Control Type '" << shadingControlType
+        << "' which requires a Schedule which is missing, it will not be translated");
     return boost::none;
   }
 
@@ -90,8 +115,6 @@ boost::optional<IdfObject> ForwardTranslator::translateShadingControl(model::Sha
   }
   idfObject.setString(WindowShadingControlFields::ZoneName, zoneName);
 
-  // Read this now, since we'll use it to test if a Warn is needed
-  std::string shadingControlType = modelObject.shadingControlType();
   idfObject.setString(WindowShadingControlFields::ShadingControlType, shadingControlType);
 
   if (zone) {
@@ -118,8 +141,6 @@ boost::optional<IdfObject> ForwardTranslator::translateShadingControl(model::Sha
     LOG(Error, modelObject.briefDescription() << " has unknown Shading Control Sequence Number");
   }
 
-  idfObject.setString(WindowShadingControlFields::MultipleSurfaceControlType, "Group");
-
   std::string shadingType = modelObject.shadingType();
   if (istringEqual("InteriorDaylightRedirectionDevice", shadingType)) {
     idfObject.setString(WindowShadingControlFields::ShadingType, "InteriorBlind");
@@ -135,30 +156,43 @@ boost::optional<IdfObject> ForwardTranslator::translateShadingControl(model::Sha
     idfObject.setString(WindowShadingControlFields::ShadingDeviceMaterialName, shadingMaterial->name().get());
   }
 
-  boost::optional<Schedule> schedule = modelObject.schedule();
-  if (schedule) {
-    idfObject.setString(WindowShadingControlFields::ScheduleName, schedule->name().get());
-    idfObject.setString(WindowShadingControlFields::ShadingControlIsScheduled, "Yes");
+  if (modelObject.isControlTypeValueAllowingSchedule()) {
+    boost::optional<Schedule> schedule = modelObject.schedule();
+    if (schedule) {
+      idfObject.setString(WindowShadingControlFields::ScheduleName, schedule->name().get());
+      idfObject.setString(WindowShadingControlFields::ShadingControlIsScheduled, "Yes");
+    } else {
+      idfObject.setString(WindowShadingControlFields::ShadingControlIsScheduled, "No");
+    }
   } else {
     idfObject.setString(WindowShadingControlFields::ShadingControlIsScheduled, "No");
   }
 
-  boost::optional<double> setpoint = modelObject.setpoint();
-  if (istringEqual("OnIfHighSolarOnWindow", shadingControlType)) {
-    if (!setpoint) {
-      setpoint = 100;  // W/m2
-    }
-    OS_ASSERT(setpoint);
-    idfObject.setDouble(WindowShadingControlFields::Setpoint, *setpoint);
+  if (modelObject.isControlTypeValueNeedingSetpoint1()) {
+    idfObject.setDouble(WindowShadingControlFields::Setpoint, modelObject.setpoint().get());
   }
 
-  idfObject.setString(WindowShadingControlFields::GlareControlIsActive, "No");
+  if (modelObject.glareControlIsActive() || istringEqual("OnIfHighGlare", shadingControlType)) {
+    idfObject.setString(WindowShadingControlFields::GlareControlIsActive, "Yes");
+  } else {
+    idfObject.setString(WindowShadingControlFields::GlareControlIsActive, "No");
+  }
 
-  //idfObject.setString(WindowShadingControlFields::TypeofSlatAngleControlforBlinds, "FixedSlatAngle");
+  boost::optional<Schedule> slatAngleSchedule = modelObject.slatAngleSchedule();
+  if (slatAngleSchedule) {
+    idfObject.setString(WindowShadingControlFields::SlatAngleScheduleName, slatAngleSchedule->name().get());
+    idfObject.setString(WindowShadingControlFields::TypeofSlatAngleControlforBlinds, "ScheduledSlatAngle");
+  } else {
+    if (!istringEqual("ScheduledSlatAngle", modelObject.typeofSlatAngleControlforBlinds())) {
+      idfObject.setString(WindowShadingControlFields::TypeofSlatAngleControlforBlinds, modelObject.typeofSlatAngleControlforBlinds());
+    }
+  }
 
-  //idfObject.setString(WindowShadingControlFields::SlatAngleScheduleName, "");
+  if (modelObject.isControlTypeValueNeedingSetpoint2()) {
+    idfObject.setDouble(WindowShadingControlFields::Setpoint2, modelObject.setpoint2().get());
+  }
 
-  //idfObject.setDouble(WindowShadingControlFields::Setpoint2, 0.0);
+  idfObject.setString(WindowShadingControlFields::MultipleSurfaceControlType, modelObject.multipleSurfaceControlType());
 
   idfObject.clearExtensibleGroups();
   for (const SubSurface& subSurface : subSurfaces) {

src/energyplus/ForwardTranslator/ForwardTranslateSubSurface.cpp

@@ -36,8 +36,6 @@
 #include "../../model/Surface_Impl.hpp"
 #include "../../model/ConstructionBase.hpp"
 #include "../../model/ConstructionBase_Impl.hpp"
-#include "../../model/ShadingControl.hpp"
-#include "../../model/ShadingControl_Impl.hpp"
 #include "../../model/WindowPropertyFrameAndDivider.hpp"
 #include "../../model/WindowPropertyFrameAndDivider_Impl.hpp"
 #include "../../model/SurfacePropertyOtherSideCoefficients.hpp"

src/energyplus/ReverseTranslator.cpp

@@ -1069,6 +1069,11 @@ boost::optional<ModelObject> ReverseTranslator::translateAndMapWorkspaceObject(c
     modelObject = translateWindowPropertyFrameAndDivider(workspaceObject);
     break;
   }
+  case openstudio::IddObjectType::WindowShadingControl:
+  {
+    modelObject = translateWindowShadingControl(workspaceObject);
+    break;
+  }
   case openstudio::IddObjectType::Zone:
     {
       modelObject = translateZone(workspaceObject);

src/energyplus/ReverseTranslator.hpp

@@ -347,6 +347,8 @@ class ENERGYPLUS_API ReverseTranslator {
 
   boost::optional<model::ModelObject> translateWindowPropertyFrameAndDivider(const WorkspaceObject & workspaceObject);
 
+  boost::optional<model::ModelObject> translateWindowShadingControl(const WorkspaceObject & workspaceObject);
+
   boost::optional<model::ModelObject> translateZone(const WorkspaceObject & workspaceObject);
 
   boost::optional<model::ModelObject> translateZoneAirHeatBalanceAlgorithm(const WorkspaceObject & workspaceObject);

src/energyplus/ReverseTranslator/ReverseTranslateFenestrationSurfaceDetailed.cpp

@@ -169,14 +169,6 @@ OptionalModelObject ReverseTranslator::translateFenestrationSurfaceDetailed( con
     subSurface->setViewFactortoGround(*d);
   }
 
-  //target = workspaceObject.getTarget(openstudio::FenestrationSurface_DetailedFields::ShadingControlName);
-  //if (target){
-  //  OptionalModelObject modelObject = translateAndMapWorkspaceObject(*target);
-  //  if (modelObject && modelObject->optionalCast<model::ShadingControl>()){
-  //    subSurface->setShadingControl(modelObject->cast<model::ShadingControl>());
-  //  }
-  //}
-
   target = workspaceObject.getTarget(openstudio::FenestrationSurface_DetailedFields::FrameandDividerName);
   if (target){
     OptionalModelObject modelObject = translateAndMapWorkspaceObject(*target);