Support all Shading Control Types in ShadingControl Object

[asparke2]

Fully support all Shading Control Types in ShadingControl Object

The OpenStudio IDD for the OS:ShadingControl object nominally supports a bunch of Shading Control Types (see IDD excerpt below). These were added in a PR in 2019. This limited implementation does not actually work for all of the control types because of the model and forward translator code for this object, as described below.

First, the OpenStudio C++ code for the .setSetpoint() method currently only sets the Setpoint if the Shading Control Type = OnIfHighSolarOnWindow. Similarly, the OpenStudio C++ code for the .setShadingControlType() method actually resets the Setpoint field unless the Shading Control Type = OnIfHighSolarOnWindow. Additionally, at least four of the possible Shading Control Type options require use of the Setpoint 2 field, which is not available in the API and is not forward translated.

Because the forward translator code only translates the Setpoint field to the IDF if the Shading Control Type = OnIfHighSolarOnWindow, even using the workspace Object.setString() workaround can't be applied to this objecct.

  A6 , \field Shading Control Type
       \type choice
       \key AlwaysOn
       \key AlwaysOff
       \key OnIfScheduleAllows
       \note OnIfScheduleAllows requires that Schedule Name be specified and
       \note Shading Control Is Scheduled = Yes.
       \note AlwaysOn, AlwaysOff and OnIfScheduleAllows are the only valid control types for ExteriorScreen.
       \note The following six control types are used primarily to reduce
       \note zone cooling load due to window solar gain
       \key OnIfHighSolarOnWindow
       \key OnIfHighHorizontalSolar
       \key OnIfHighOutdoorAirTemperature
       \key OnIfHighZoneAirTemperature
       \key OnIfHighZoneCooling
       \key OnIfHighGlare
       \note Following entry should be used only if Shading Type = SwitchableGlazing
       \note and window is in a daylit zone
       \key MeetDaylightIlluminanceSetpoint
       \note The following three control types are used to reduce zone Heating load. They can be
       \note used with any Shading Type but are most appropriate for opaque interior or exterior
       \note shades with high insulating value ("opaque movable insulation")
       \key OnNightIfLowOutdoorTempAndOffDay
       \key OnNightIfLowInsideTempAndOffDay
       \key OnNightIfHeatingAndOffDay
       \note The following two control types are used to reduce zone heating and cooling load.
       \note They can be used with any Shading Type but are most appropriate for translucent interior
       \note or exterior shades with high insulating value ("translucent movable insulation")
       \key OnNightIfLowOutdoorTempAndOnDayIfCooling
       \key OnNightIfHeatingAndOnDayIfCooling
       \note The following two control types are used to reduce zone Cooling load.
       \note They can be used with any Shading Type but are most appropriate for interior
       \note or exterior blinds,interior or exterior shades with low insulating value, or
       \note switchable glazing
       \key OffNightAndOnDayIfCoolingAndHighSolarOnWindow
       \key OnNightAndOnDayIfCoolingAndHighSolarOnWindow
       \note The following four control types require that both Setpoint and Setpoint2 be specified
       \note Setpoint will correspond to outdoor air temp or zone air temp (deg C)
       \note Setpoint2 will correspond to solar on window or horizontal solar (W/m2)
       \key OnIfHighOutdoorAirTempAndHighSolarOnWindow
       \key OnIfHighOutdoorAirTempAndHighHorizontalSolar
       \key OnIfHighZoneAirTempAndHighSolarOnWindow
       \key OnIfHighZoneAirTempAndHighHorizontalSolar
       \default OnIfHighSolarOnWindow

Possible Implementation

Read through the IDD options and revise the API accordingly.

[jmarrec]

I found this problem independently while working on #4066, I came to open the issue only to realize you beat me to it, and the issue is well detailed. What I wrote on slack earlier is about the same, see below:

---

The default setpoint is 27 (W/m2, since it relates OnIfHighSolarOnWindow only ) in the model API

OpenStudio/src/model/ShadingControl.cpp

Lines 130 to 140 in 2aeb103

	boost::optional<double> ShadingControl_Impl::setpoint() const
	{
	boost::optional<double> result = getDouble(OS_ShadingControlFields::Setpoint);
	if (!result){
	std::string shadingControlType = this->shadingControlType();
	if (istringEqual("OnIfHighSolarOnWindow", shadingControlType)){
	result = 27; // w/m^2
	}
	}
	return result;
	}

yet the FT for some obscure reason has a block (which will never be entered) that uses 100 W/m2

OpenStudio/src/energyplus/ForwardTranslator/ForwardTranslateShadingControl.cpp

Lines 146 to 153 in 2aeb103

	boost::optional<double> setpoint = modelObject.setpoint();
	if (istringEqual("OnIfHighSolarOnWindow", shadingControlType)) {
	if (!setpoint) {
	setpoint = 100; // W/m2
	}
	OS_ASSERT(setpoint);
	idfObject.setDouble(WindowShadingControlFields::Setpoint, *setpoint);
	}

Much Worse, there are like 10 Shading Control Type values that expect a setpoint (or two), and yet you can't set the setpoint for any of them but the OnIfHighSolarOnWindow and Setpoint2 is unavailable in the API.

OpenStudio/src/model/ShadingControl.cpp

Lines 194 to 202 in 2aeb103

	bool ShadingControl_Impl::setSetpoint(double setpoint)
	{
	bool result = false;
	std::string shadingControlType = this->shadingControlType();
	if (istringEqual("OnIfHighSolarOnWindow", shadingControlType)){
	result = setDouble(OS_ShadingControlFields::Setpoint, setpoint);
	}
	return result;
	}

example of a ShadingControlType you cannot use:

OnIfHighOutdoorAirTemperature: Shading is on if outside air temperature exceeds SetPoint (C) and schedule, if specified, allows shading

[jmarrec]

Additionally: all of these fields are problematic:

  A8 , \field Shading Control Is Scheduled
       \type choice
       \key No
       \key Yes
       \default No
       \note If Yes, Schedule Name is required; if No, Schedule Name is not used.
       \note Shading Control Is Scheduled = Yes is required if Shading Control Type = OnIfScheduleAllows.
  A9 , \field Glare Control Is Active
       \type choice
       \key No
       \key Yes
       \default No
       \note If Yes and window is in a daylit zone, shading is on if zone's discomfort glare index exceeds
       \note the maximum discomfort glare index specified in the Daylighting object referenced by the zone.
       \note The glare test is OR'ed with the test specified by Shading Control Type.
       \note Glare Control Is Active = Yes is required if Shading Control Type = OnIfHighGlare.
  A10, \field Type of Slat Angle Control for Blinds
       \type choice
       \key FixedSlatAngle
       \key ScheduledSlatAngle
       \key BlockBeamSolar
       \default FixedSlatAngle
       \note Used only if Shading Type = InteriorBlind, ExteriorBlind or BetweenGlassBlind.
       \note If choice is ScheduledSlatAngle then Slat Angle Schedule Name is required.
  A11, \field Slat Angle Schedule Name
       \type object-list
       \object-list ScheduleNames
       \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)

Shading Control Is Scheduled is set if you assign a Schedule to it so it's redundant, see

OpenStudio/src/model/ShadingControl.cpp

Lines 189 to 197 in 2aeb103

	test = setString(OS_ShadingControlFields::ShadingControlIsScheduled, "No");
	OS_ASSERT(test);
	}
	bool ShadingControl_Impl::setSetpoint(double setpoint)
	{
	bool result = false;
	std::string shadingControlType = this->shadingControlType();

The rest of them aren't even being used.

---

Edit:: Setpoint2 was implemented already in #4066

  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