Merge remote-tracking branch 'remotes/origin/develop' into reduceDayl…

…ightingAllocations

.gitignore

@@ -22,6 +22,7 @@
 
 # EPLaunch workflow cache files
 .eplaunch
+testfiles/EPLaunchRun_*/
 
 # this is autogenerated in the src dir
 doc/title.tex

datasets/CodeCompliantEquipment.idf

@@ -64,10 +64,10 @@
 !-     The curve should be used as input to the following field:
 !-     "Electric Input to Cooling Output Ratio Function of Part Load Ratio Curve Name"
 
-!- Set of performance curves for ASHRAE901_2019_air_A_gte150ton_10.1kWpton_14IPLV.IP
+!- Set of performance curves for ASHRAE901_2019_air_A_gte150ton_10.1EER_14IPLV.IP
 
 Curve:Biquadratic,
-    ASHRAE901_2019_air_A_gte150ton_10.1kWpton_14IPLV.IP_cap-f-t,    !- Name
+    ASHRAE901_2019_air_A_gte150ton_10.1EER_14IPLV.IP_cap-f-t,    !- Name
     0.7869057566821718,       !- Coefficient1 Constant
     0.06561212364217481,      !- Coefficient2 x
     -0.002301768917046292,    !- Coefficient3 x2
@@ -82,7 +82,7 @@ Curve:Biquadratic,
     ;                         !- Maximum Curve Output
 
 Curve:Biquadratic,
-    ASHRAE901_2019_air_A_gte150ton_10.1kWpton_14IPLV.IP_eir-f-t,    !- Name
+    ASHRAE901_2019_air_A_gte150ton_10.1EER_14IPLV.IP_eir-f-t,    !- Name
     0.872388053480053,        !- Coefficient1 Constant
     -0.02372502054976646,     !- Coefficient2 x
     0.0011453381173352607,    !- Coefficient3 x2
@@ -97,7 +97,7 @@ Curve:Biquadratic,
     ;                         !- Maximum Curve Output
 
 Curve:Cubic,
-    ASHRAE901_2019_air_A_gte150ton_10.1kWpton_14IPLV.IP_eir-f-plr,    !- Name
+    ASHRAE901_2019_air_A_gte150ton_10.1EER_14IPLV.IP_eir-f-plr,    !- Name
     0.16266507402733643,      !- Coefficient1 Constant
     0.09082153641729536,      !- Coefficient2 x
     1.369885791798356,        !- Coefficient3 x2
@@ -148,10 +148,10 @@ Curve:Cubic,
     1.0,                      !- Maximum Value of x
     ;                         !- Minimum Curve Output
 
-!- Set of performance curves for ASHRAE901_2019_air_A_lt150ton_10.1kWpton_13.7IPLV.IP
+!- Set of performance curves for ASHRAE901_2019_air_A_lt150ton_10.1EER_13.7IPLV.IP
 
 Curve:Biquadratic,
-    ASHRAE901_2019_air_A_lt150ton_10.1kWpton_13.7IPLV.IP_cap-f-t,    !- Name
+    ASHRAE901_2019_air_A_lt150ton_10.1EER_13.7IPLV.IP_cap-f-t,    !- Name
     0.7536274941282223,       !- Coefficient1 Constant
     0.059276028733216114,     !- Coefficient2 x
     -0.002073292464305097,    !- Coefficient3 x2
@@ -166,7 +166,7 @@ Curve:Biquadratic,
     ;                         !- Maximum Curve Output
 
 Curve:Biquadratic,
-    ASHRAE901_2019_air_A_lt150ton_10.1kWpton_13.7IPLV.IP_eir-f-t,    !- Name
+    ASHRAE901_2019_air_A_lt150ton_10.1EER_13.7IPLV.IP_eir-f-t,    !- Name
     0.9908215848761304,       !- Coefficient1 Constant
     -0.02794659902518455,     !- Coefficient2 x
     0.0012289343079591177,    !- Coefficient3 x2
@@ -181,7 +181,7 @@ Curve:Biquadratic,
     ;                         !- Maximum Curve Output
 
 Curve:Cubic,
-    ASHRAE901_2019_air_A_lt150ton_10.1kWpton_13.7IPLV.IP_eir-f-plr,    !- Name
+    ASHRAE901_2019_air_A_lt150ton_10.1EER_13.7IPLV.IP_eir-f-plr,    !- Name
     0.1271245020760697,       !- Coefficient1 Constant
     0.07474000662382732,      !- Coefficient2 x
     1.6429989224609347,       !- Coefficient3 x2
@@ -232,10 +232,10 @@ Curve:Cubic,
     1.0,                      !- Maximum Value of x
     ;                         !- Minimum Curve Output
 
-!- Set of performance curves for ASHRAE901_2019_air_B_gte150ton_9.7kWpton_16.1IPLV.IP
+!- Set of performance curves for ASHRAE901_2019_air_B_gte150ton_9.7EER_16.1IPLV.IP
 
 Curve:Biquadratic,
-    ASHRAE901_2019_air_B_gte150ton_9.7kWpton_16.1IPLV.IP_cap-f-t,    !- Name
+    ASHRAE901_2019_air_B_gte150ton_9.7EER_16.1IPLV.IP_cap-f-t,    !- Name
     0.7640172447555345,       !- Coefficient1 Constant
     0.06804849058816334,      !- Coefficient2 x
     -0.0023096145622898837,    !- Coefficient3 x2
@@ -250,7 +250,7 @@ Curve:Biquadratic,
     ;                         !- Maximum Curve Output
 
 Curve:Biquadratic,
-    ASHRAE901_2019_air_B_gte150ton_9.7kWpton_16.1IPLV.IP_eir-f-t,    !- Name
+    ASHRAE901_2019_air_B_gte150ton_9.7EER_16.1IPLV.IP_eir-f-t,    !- Name
     0.8376257618251238,       !- Coefficient1 Constant
     -0.02517196794784297,     !- Coefficient2 x
     0.0012343872931018665,    !- Coefficient3 x2
@@ -265,7 +265,7 @@ Curve:Biquadratic,
     ;                         !- Maximum Curve Output
 
 Curve:Cubic,
-    ASHRAE901_2019_air_B_gte150ton_9.7kWpton_16.1IPLV.IP_eir-f-plr,    !- Name
+    ASHRAE901_2019_air_B_gte150ton_9.7EER_16.1IPLV.IP_eir-f-plr,    !- Name
     0.07524240756710364,      !- Coefficient1 Constant
     0.031402409184518115,     !- Coefficient2 x
     1.7196158727669184,       !- Coefficient3 x2
@@ -316,10 +316,10 @@ Curve:Cubic,
     1.0,                      !- Maximum Value of x
     ;                         !- Minimum Curve Output
 
-!- Set of performance curves for ASHRAE901_2019_air_B_lt150ton_9.7kWpton_15.8IPLV.IP
+!- Set of performance curves for ASHRAE901_2019_air_B_lt150ton_9.7EER_15.8IPLV.IP
 
 Curve:Biquadratic,
-    ASHRAE901_2019_air_B_lt150ton_9.7kWpton_15.8IPLV.IP_cap-f-t,    !- Name
+    ASHRAE901_2019_air_B_lt150ton_9.7EER_15.8IPLV.IP_cap-f-t,    !- Name
     0.7332916635331697,       !- Coefficient1 Constant
     0.06832466267947408,      !- Coefficient2 x
     -0.00227257048344532,     !- Coefficient3 x2
@@ -334,7 +334,7 @@ Curve:Biquadratic,
     ;                         !- Maximum Curve Output
 
 Curve:Biquadratic,
-    ASHRAE901_2019_air_B_lt150ton_9.7kWpton_15.8IPLV.IP_eir-f-t,    !- Name
+    ASHRAE901_2019_air_B_lt150ton_9.7EER_15.8IPLV.IP_eir-f-t,    !- Name
     0.8024149509361447,       !- Coefficient1 Constant
     -0.020856081428500536,    !- Coefficient2 x
     0.0011199744452278892,    !- Coefficient3 x2
@@ -349,7 +349,7 @@ Curve:Biquadratic,
     ;                         !- Maximum Curve Output
 
 Curve:Cubic,
-    ASHRAE901_2019_air_B_lt150ton_9.7kWpton_15.8IPLV.IP_eir-f-plr,    !- Name
+    ASHRAE901_2019_air_B_lt150ton_9.7EER_15.8IPLV.IP_eir-f-plr,    !- Name
     0.08666141661681519,      !- Coefficient1 Constant
     0.019140365295631154,     !- Coefficient2 x
     1.6920073253734107,       !- Coefficient3 x2

design/FY2021/NFP-CoilSpeedEMSActuators.md

@@ -0,0 +1,49 @@
+# Adding Multispeed Coil Speed Level Control Actuators
+
+**Xuan Luo, Yujie Xu, Tianzhen Hong, Lawrence Berkeley National Laboratory**
+
+- July 2, 2021 - Initial Draft
+
+## Justification for Feature Update
+
+GEBs (Grid-interactive efficient buildings) can respond to grid or pricing signals by adjusting the operation of lighting, plug-in equipment, and HVAC systems. Adjusting HVAC operation strategies include changing thermostat setpoints, turning equipment on/off, and adjusting the speed or capacity of variable-speed or multi-speed compressors and fans.
+
+The typical EnergyPlus approach to modeling two-speed and variable-speed coils is to have a constant setpoint without a deadband and find the appropriate speed ratio to perfectly meet the load. Deadband thermostats are already included in EnergyPlus, but new control logic is needed to model realistic coil behavior to take advantage of this feature. For two-speed residential equipment, when the coil first turns on, it starts at speed 1 for several minutes, checks if the space temperature is moving in the right direction, and then either stays at speed 1 or moves to speed 2.
+
+To resolve this, we propose to make the coil speed level actuatable in EMS. Allowing the coil speed to be actuatable would give a much wider flexibility to model HVAC speed switch strategies that are not limited to the control logic. For example, it would enable variable speed coils (using the DX multispeed object) to exhibit the behavior specified in response to certain load shedding events where the coil can still run, but not at more than a certain percent of the maximum capacity (70% during shed events in AHRI standard 1380).
+
+## Overview
+
+We propose to make the speed level of the cooling and heating multispeed coils, namely `Coil:Cooling:DX:MultiSpeed` and `Coil:Heating:DX:Multispeed`, actuable. Both the multispeed cooling and heating coil can only be referenced by an `AirLoopHVAC:UnitarySystem` or `AirLoopHVAC:UnitaryHeatPump:AirToAir:Multispeed` object.
+
+Currently, both `AirLoopHVAC:UnitarySystem` or `AirLoopHVAC:UnitaryHeatPump` have a reportable variable “Unitary System DX Coil Speed Level” indicating the index of the speed level, and the variable is originally controlled either by load or temperature. We will add EMS actuators to both speed level indices of the unitary system and unitary heat pump, and overwrite the values of both variables at the end of the control logic. We will also add and appropriate EnergyPlus API functionality to allow users to actuate these controls from the EnergyPlus Python Plugin System.
+
+## Approach
+
+The actuators will be implemented to override the unitary system DX coil speed level.
+
+Actuator-specific unique key values are determined from the unitary system (or unitary heat pump) name. 
+The following example Python codes show a possible implementation of the unique handler.
+
+```python
+comp_type = "AirLoopHVAC:UnitaryHeatPump:AirToAir:MultiSpeed"
+ctrl_type = "Unitary System DX Coil Speed Level"
+
+unitary_system_name =  "TwoSpeed Heat Pump 1"
+actuator_key = f"{unitary_system_name}"
+
+k_handle = self.api.exchange.get_actuator_handle(state, comp_type, ctrl_type, actuator_key)
+```
+
+## Testing/Validation/Data Source(s)
+
+A new example file built upon the existing file, `SingleFamilyHouse_TwoSpeed_ZoneAirBalance.idf` with a unitary heat pump, will be created to demonstrate the use of the new feature EMS actuators and appropriate E+ API. Simulation results will be manually checked.
+
+## Email Discussion
+
+The feature and implementation details were discussed at one of the EnergyPlus Technicality calls. A separate call was also organized with LBNL, NREL, and ORNL teams.
+
+## References
+
+Another branch `HVACFlexMeasures`, owned by ORNL, is working on developing HVAC flexibility measures in EnergyPlus to assess impact of grid-responsive building equipment technologies and energy storage. The coil side focuses on variable-speed coils.
+

doc/ems-application-guide/src/ems-actuators/hvac-systems-001.tex

@@ -134,6 +134,12 @@ \subsection{Unitary Equipment}\label{unitary-equipment}
   An actuator called ``AirLoopHVAC:UnitaryHeatPump:WaterToAir'' is available with control type ``Autosized Supply Air Flow Rate.''
 \end{itemize}
 
+An actuator called ``Coil Speed Control'' is available with control type ``Unitary System DX Coil Speed Value''. This actuator is only available for the `AirLoopHVAC:UnitarySystem` or `AirLoopHVAC:UnitaryHeatPump:AirToAir:Multispeed` object, referencing multispeed DX coils.
+
+The EMS override coil speed value, “Unitary System DX Coil Speed Value”, is a continuous number below maximum coil speed level allowed. With any EMS override coil speed value, if the input value is a integer, the speed level is set as the exact speed value input, with the cycling or speed ratio = 1.0. Otherwise, if the floating point part is greater than zero, the speed level is calculated as the closest integer greater than the EMS speed value, and the cycling/speed ratio is set as the floating point part of the EMS speed value. For example, if EMS overrides coil speed value = 1.2, the speed level number is set as 2 with a speed ratio at 0.2.
+
+It should be noted that if there's no cooling or heating or moisture load presented at any time step, the coil will shut off the coil regardless of the EMS speed setting. If the Outside Dry Bulb Temperature is lower than the minimum outdoor operating temperature for heat pump compressor, the coil will also shut off regardless the EMS speed setting.
+
 \subsection{AirTerminal:SingleDuct:ConstantVolume:NoReheat}\label{airTerminalsingleductconstantvolumenoreheat}
 
 An actuator called ``AirTerminal:SingleDuct:ConstantVolume:NoReheat'' is available with a control type called ``Mass Flow Rate.''~ This actuator is available in models that use the single duct constant volume no reheat air terminal. The units are kg/s. This actuator is used to control the mass flow rate. Normally, the flow rate of single duct constant volume no reheat air terminals is fixed by the input, sizing results or OA requirement for DOA system, but this actuator provides a way to override the flow with Erl programs.

doc/engineering-reference/src/building-system-simulation-system-manager/primary-air-system-simulation.tex

@@ -101,7 +101,7 @@ \subsubsection{One Time Calculations}\label{one-time-calculations}
 
 (4)~~Similarly the outlet nodes of the AirLoopHVAC:ZoneSplitter are compared with the heating inlet nodes of all ZoneHVAC:AirDistributionUnits. A match indicates that this zone is served by heating supply air from the air loop.
 
-(5)~~The case where there is no AirLoopHVAC:ZoneSplitter for a AirLoopHVAC:SupplyPath must be handled. In this case the program looks for a match between the zone equipment inlet node and an ZoneHVAC:AirDistributionUnit heating or cooling inlet node. When a match is found that zone is identified as being served with heating or cooling supply air from the air loop.
+(5)~~The case where there is no AirLoopHVAC:ZoneSplitter for an AirLoopHVAC:SupplyPath must be handled. In this case the program looks for a match between the zone equipment inlet node and a ZoneHVAC:AirDistributionUnit heating or cooling inlet node. When a match is found that zone is identified as being served with heating or cooling supply air from the air loop.
 
 (6)~~The list of cooled and heated zones are saved in the air loop data structure AirToZoneNodeInfo.
 

doc/engineering-reference/src/simulation-models-encyclopedic-reference-001/coils.tex

@@ -2604,6 +2604,10 @@ \subsubsection{Seasonal Energy Efficiency Ratio (SEER) for Multi-Speed DX Coil}\
 \multicolumn{4}{l}{Source: AHRI Standard 210-240, 2008; Table 16, Page 94}
 \end{longtable}
 
+\subsubsection{Energy Management System Coil Speed Override}\label{energy-management-system-coil-speed-level-override-1}
+
+The cooling coil speed level and cycling/speed ratio can be actuated by EMS at run-time. When EMS is used to overwrite the “Unitary System DX Coil Speed Value”, the speed levels are set based on EMS values rather than speed levels determined by the Non-EMS EnergyPlus control logic. The EMS override coil speed value is a continuous number below maximum coil speed level allowed. With any EMS override coil speed value, if the input value is a integer, the speed level is set as the exact speed value input, with the cycling or speed ratio = 1.0. Otherwise, if the floating point part is greater than zero, the speed level is calculated as the closest integer greater than the EMS speed value, and the cycling/speed ratio is set as the floating point part of the EMS speed value. For example, if EMS overrides coil speed value = 1.2, the speed level number is set as 2 with a speed ratio at 0.2.
+
 \subsubsection{References}\label{references-3-001}
 
 See the references for the single speed DX cooling coil earlier in this document.
@@ -2770,6 +2774,10 @@ \subsubsection{Standard Ratings}\label{standard-ratings}
 
 The results for EER, COP, and supply air mass flow rate at the part load test points are reported to the EIO file and a predefined table report called VAV DX Cooling Standard Rating Details.
 
+\subsubsection{Energy Management System Coil Speed Level Override}\label{energy-management-system-coil-speed-level-override-2}
+
+The heating coil speed level and cycling/speed ratio can be actuated by EMS at run-time. When EMS is used to overwrite the “Unitary System DX Coil Speed Value”, the speed levels are set based on EMS values rather than speed levels determined by the Non-EMS EnergyPlus control logic. The EMS override coil speed value is a continuous number below maximum coil speed level allowed. With any EMS override coil speed value, if the input value is a integer, the speed level is set as the exact speed value input, with the cycling or speed ratio = 1.0. Otherwise, if the floating point part is greater than zero, the speed level is calculated as the closest integer greater than the EMS speed value, and the cycling/speed ratio is set as the floating point part of the EMS speed value. For example, if EMS overrides coil speed value = 1.2, the speed level number is set as 2 with a speed ratio at 0.2.
+
 \subsubsection{References}\label{references-4-001}
 
 See the references for the single speed DX cooling coil earlier in this document.