HVAC external capacity control (#84)

Partly addresses #72 - [x] Reference the issue your PR is fixing - [x] Assign at least 1 reviewer for your PR - [x] Test with run_dwelling.py or other script - [x] Update documentation as appropriate - [x] Update changelog as appropriate
NREL · Feb 28, 2024 · b144307 · b144307
2 parents cd9f4b0 + 9df63c9
commit b144307
Show file tree

Hide file tree

Showing 10 changed files with 273 additions and 208 deletions.
diff --git a/bin/run_external_control.py b/bin/run_external_control.py
@@ -7,11 +7,15 @@
 # Test script to run single Dwelling with constant external control signal
 
 dwelling_args.update({
+    'time_res': dt.timedelta(minutes=10),
     'ext_time_res': dt.timedelta(minutes=60),  # for duty cycle control only
 })
 
 example_control_signal = {
-    'HVAC Heating': {'Setpoint': 19},  # in C
+    'HVAC Heating': {'Setpoint': 19,
+                    #  'Max Capacity Fraction': 0.8,
+                     'Max ER Capacity Fraction': 0.5,
+                     },  # in C
     'HVAC Cooling': {'Setpoint': 22},  # in C
     'Water Heating': {'Setpoint': 50},  # in C
     'PV': {'P Setpoint': -1.1, 'Q Setpoint': 0.5},  # in kW, kVAR
@@ -36,30 +40,31 @@ def run_with_schedule_control():
     dwelling.simulate()
 
 
-def run_constant_control_signal(control_signal):
+def run_constant_control_signal(control_signal=None):
     # Initialization
-    dwelling = Dwelling(name='Test House with Controller', **dwelling_args)
+    dwelling = Dwelling(name='OCHRE with Controller', **dwelling_args)
 
     # Simulation
     for t in dwelling.sim_times:
-        assert dwelling.current_time == t
+        # assert dwelling.current_time == t
         house_status = dwelling.update(control_signal=control_signal)
 
-    return dwelling.finalize()
+    df, _, _ = dwelling.finalize()
 
 
 def get_hvac_controls(hour_of_day, occupancy, heating_setpoint, **unused_inputs):
     # Use some of the controller_inputs to determine setpoints (or other control signals)
     if 14 <= hour_of_day < 20:  # 2PM-8PM
-        if occupancy > 0:
-            heating_setpoint -= 1  # reduce setpoint by 1 degree C
-        else:
-            heating_setpoint -= 2  # reduce setpoint by 2 degrees C
+        heating_setpoint -= 1  # reduce setpoint by 1 degree C
+        # if occupancy > 0:
+        #     heating_setpoint -= 1  # reduce setpoint by 1 degree C
+        # else:
+        #     heating_setpoint -= 2  # reduce setpoint by 2 degrees C
 
     return {
-            # 'HVAC Heating': {'Duty Cycle': 1 if heating_on else 0},
             'HVAC Heating': {
-                'Setpoint': heating_setpoint,
+                'Capacity': 1000,
+                # 'Setpoint': heating_setpoint,
                 #  'Deadband': 2,
                 # 'Load Fraction': 0,  # Set to 0 for force heater off
                 # 'Duty Cycle': 0.5,  # Sets fraction of on-time explicitly
@@ -70,7 +75,7 @@ def get_hvac_controls(hour_of_day, occupancy, heating_setpoint, **unused_inputs)
 
 def run_with_hvac_controller():
     # Initialization
-    dwelling = Dwelling(name='Test House with Controller', **dwelling_args)
+    dwelling = Dwelling(name="OCHRE with Controller", **dwelling_args)
     heater = dwelling.get_equipment_by_end_use('HVAC Heating')
     cooler = dwelling.get_equipment_by_end_use('HVAC Cooling')
 
@@ -113,7 +118,7 @@ def run_controls_from_file(control_file):
     df_ext = pd.read_csv(control_file, index_col='Time', parse_dates=True)
 
     # Initialization
-    dwelling = Dwelling(name='Test House with Controller', **dwelling_args)
+    dwelling = Dwelling(name="OCHRE with Controller", **dwelling_args)
 
     # Simulation
     control_signal = None
@@ -130,5 +135,5 @@ def run_controls_from_file(control_file):
 if __name__ == '__main__':
     # run_with_schedule_control()
     # run_constant_control_signal(example_control_signal)
-    # run_controls_from_file(external_control_file='path/to/control_file.csv')
-    run_with_hvac_controller()
+    run_with_hvac_controller()
+    # run_controls_from_file(external_control_file='path/to/control_file.csv')
diff --git a/bin/run_multiple.py b/bin/run_multiple.py
@@ -138,7 +138,6 @@ def run_single_building(input_path, simulation_name='ochre', output_path=None):
 def compile_results(main_folder):
     # Sample script to compile results from multiple OCHRE runs
     # assumes each run is in a different folder, and all simulation names are 'ochre'
-    dirs_to_include = int(dirs_to_include)
 
     # set up
     main_folder = os.path.abspath(main_folder)

diff --git a/changelog.md b/changelog.md
@@ -2,8 +2,12 @@
 
 ### Changes from PRs
 
+- Added HVAC capacity and max capacity controls, ideal mode only
+- Require HVAC duty cycle control for thermostatic mode only
 - Fixed bug with accounting for HVAC delivered heat for standalone HVAC runs 
 - Fixed bug with ASHP backup heater units
+- Fixed bug with named HVAC/Water Heating equipment arguments
+- Fixed bug in ASHP duty cycle control
 - Added OCHREException class to handle errors
 
 ### OCHRE v0.8.4-beta

diff --git a/docs/source/ControllerIntegration.rst b/docs/source/ControllerIntegration.rst
@@ -31,15 +31,29 @@ equipment, by end use.
 
 HVAC Heating or HVAC Cooling
 ----------------------------
-================================  ==========  ========================================================================= 
-**Control Command**               **Units**   **Description**     
-================================  ==========  ========================================================================= 
-Load Fraction                     unitless    1 (no effect) or 0 (force equipment off)
-Setpoint                          C           Sets temperature setpoint for one timestep (then reverts to schedule)
-Deadband                          C           Sets thermostat deadband (does not revert unless deadband is scheduled)
-Duty Cycle                        unitless    Sets the equipment duty cycle for ``ext_time_res``
-Disable Speed X                   unitless    Disables low (X=1) or high (X=2) speed if value is ``True`` [#]_
-================================  ==========  =========================================================================
++-------------------------------+--------------------------+-----------+-------------------------------------------------------------------------------------+
+| **End Use or Equipment Name** | **Control Command**      | **Units** | **Description**                                                                     |
++===============================+==========================+===========+=====================================================================================+
+| HVAC Heating or HVAC Cooling  | Load Fraction            | unitless  | 1 (no effect) or 0 (forces equipment off)                                           |
++-------------------------------+--------------------------+-----------+-------------------------------------------------------------------------------------+
+| HVAC Heating or HVAC Cooling  | Setpoint                 | C         | Sets temperature setpoint for one timestep (then reverts back to schedule)          |
++-------------------------------+--------------------------+-----------+-------------------------------------------------------------------------------------+
+| HVAC Heating or HVAC Cooling  | Deadband                 | C         | Sets temperature deadband (does not revert back unless deadband is in the schedule) |
++-------------------------------+--------------------------+-----------+-------------------------------------------------------------------------------------+
+| HVAC Heating or HVAC Cooling  | Capacity                 | W         | Sets HVAC capacity directly, ideal capacity only (reverts back to defaults)         |
++-------------------------------+--------------------------+-----------+-------------------------------------------------------------------------------------+
+| HVAC Heating or HVAC Cooling  | Max Capacity Fraction    | unitless  | Limits HVAC max capacity, ideal capacity only (does not revert)                     |
++-------------------------------+--------------------------+-----------+-------------------------------------------------------------------------------------+
+| HVAC Heating or HVAC Cooling  | Duty Cycle               | unitless  | Sets the equipment duty cycle for ext_time_res, non-ideal capacity only             |
++-------------------------------+--------------------------+-----------+-------------------------------------------------------------------------------------+
+| HVAC Heating or HVAC Cooling  | Disable Speed X          | N/A       | Disables low (X=1) or high (X=2) speed if value is ``True`` [#]_                    |
++-------------------------------+--------------------------+-----------+-------------------------------------------------------------------------------------+
+| HVAC Heating (ASHP only)      | ER Capacity              | W         | Sets ER element capacity directly, ideal capacity only (reverts back to defaults)   |
++-------------------------------+--------------------------+-----------+-------------------------------------------------------------------------------------+
+| HVAC Heating (ASHP only)      | Max ER Capacity Fraction | unitless  | Limits ER element max capacity, ideal capacity only (does not revert)               |
++-------------------------------+--------------------------+-----------+-------------------------------------------------------------------------------------+
+| HVAC Heating (ASHP only)      | ER Duty Cycle            | unitless  | Sets the ER element duty cycle for ext_time_res, non-ideal capacity only            |
++-------------------------------+--------------------------+-----------+-------------------------------------------------------------------------------------+
 
 .. [#] Only available for 2 speed equipment, either ASHP or AC. Variable speed equipment modulates between all speeds to
          perfectly maintain setpoint ( deadband = 0 C)

diff --git a/docs/source/ModelingApproach.rst b/docs/source/ModelingApproach.rst
@@ -135,60 +135,65 @@ HVAC
 ----
 
 OCHRE models several different types of heating, ventilation, and air
-conditioning (HVAC) technologies commonly found in residential buildings
-in the United States. This includes furnaces, boilers, electric
-resistance baseboards, central air conditioners (ACs), room air
-conditioners, air source heat pumps (ASHPs), and minisplit heat pumps
-(MSHPs). OCHRE also includes “ideal” heating and cooling equipment
-models that perfectly maintain the indoor setpoint temperature with a
-constant efficiency. Ideal equipment is useful for debugging and
-determining the loads in a building.
-
-HVAC equipment use three types of algorithms for determining equipment
-capacity and efficiency:
-
--  Static capacity: System capacity and efficiency is set at
+conditioning (HVAC) technologies commonly found in residential buildings in
+the United States. This includes furnaces, boilers, electric resistance
+baseboards, central air conditioners (ACs), room air conditioners, air source
+heat pumps (ASHPs), and minisplit heat pumps (MSHPs). OCHRE also includes
+“ideal” heating and cooling equipment models that perfectly maintain the
+indoor setpoint temperature with a constant efficiency.
+
+HVAC equipment use one of two algorithms to determine equipment max capacity
+and efficiency:
+
+-  Static: System max capacity and efficiency is set at
    initialization and does not change (e.g., Gas Furnace, Electric
-   Baseboard)
-
--  Dynamic capacity: System capacity and efficiency varies based on
-   indoor and outdoor temperatures and air flow rate (e.g., Air
-   Conditioner, Air Source Heat Pump)
-
--  Ideal capacity: System capacity is calculated at each time step to
-   maintain constant indoor temperature (e.g., Ideal Heater, Ideal
-   Cooler)
-
-Air source heat pumps, minisplit heat pumps, and air conditioners
-include multi-speed options, including single-speed, two-speed, and
-variable speed options. The one- and two-speed options typically use the
-dynamic capacity algorithm for high resolution simulations, while the
-variable speed option typically uses the ideal capacity algorithm. This
-equipment use curves to determine the capacity of efficiency of the unit
-as a function of the outdoor air drybulb temperature and indoor air
-wetbulb temperature. These curves are based on “\ `Improved Modeling of
-Residential Air Conditioners and Heat Pumps for Energy
-Calculations <https://scholar.colorado.edu/concern/graduate_thesis_or_dissertations/r781wg40j>`__\ ”.
-Minisplit heat pumps are always modeled as multispeed equipment, while
-for other equipment multiple options are available, with more speeds
-corresponding to higher efficiency equipment.
-
-The Air Source Heat Pump and Mini Split Heat Pump models include heating
-and cooling functionality. The heat pump heating model includes a
-reverse cycle defrost algorithm that reduces efficiency and capacity at
-low temperatures, as well as an electric resistance element that is
-enabled when the outdoor air temperature is below a threshold.
-
-By default, HVAC equipment are controlled using a thermostat control.
-Heating and cooling setpoints are defined in the input files and can
-vary over time.
-
-All HVAC equipment can be externally controlled by updating the
-thermostat setpoints and deadband or by direct load control (i.e.,
-shut-off). Static and dynamic HVAC equipment can also be controlled
-using duty cycle control or by disabling specific speeds. The equipment
-will follow the duty cycle control exactly while minimizing temperature
-deviation from setpoint and minimizing cycling.
+   Baseboard).
+
+-  Dynamic: System max capacity and efficiency varies based on indoor and
+   outdoor temperatures and air flow rate using biquadratic formulas. These
+   curves are based on “\ `Improved Modeling of Residential Air Conditioners
+   and Heat Pumps for Energy Calculations
+<https://scholar.colorado.edu/concern/graduate_thesis_or_dissertations/r781wg40j>`__\
+” (e.g.,  Air Conditioner, Air Source Heat Pump).
+
+In addition, HVAC equipment use one of two modes to determine real-time
+capacity and power consumption:
+
+-  Thermostatic mode: A thermostat control with a deadband is used to
+   turn the equipment on and off. Capacity and power are zero or at their
+   maximum values.
+
+-  Ideal mode: Capacity is calculated at each time step to perfectly
+   maintain the indoor setpoint temperature. Power is determined by the
+   fraction of time that the equipment is on in various modes.
+
+By default, most HVAC equipment operate in thermostatic mode for simulations
+with a time resolution of less than 5 minutes. Otherwise, the ideal mode is
+used. The only exceptions are variable speed equipment, which always operate
+in ideal capacity mode.
+
+Air source heat pumps, central air conditioners, and room air conditioners
+include single-speed, two-speed, and variable speed options. Minisplit heat
+pumps are always modeled as variable speed equipment.
+
+The Air source heat pump and Minisplit heat pump models include heating and
+cooling functionality. The heat pump heating model includes a few unique
+features:
+
+-  An electric resistance element with additional controls, including an
+   offset thermostat deadband.
+-  A heat pump shut off control when the outdoor air temperature is below a
+   threshold.
+-  A reverse cycle defrost algorithm that reduces heat pump efficiency and
+   capacity at low temperatures.
+
+All HVAC equipment can be externally controlled by updating the thermostat
+setpoints and deadband or by direct load control (i.e., shut-off). Specific
+speeds can be disabled in multi-speed equipment. Equipment capacity can also
+be set directly or controlled using a maximum capacity fraction in ideal mode.
+In thermostatic mode, duty cycle controls can determine the equipment state.
+The equipment will follow the duty cycle control exactly while minimizing
+cycling and temperature deviation from setpoint. 
 
 Ducts
 ~~~~~

diff --git a/ochre/Dwelling.py b/ochre/Dwelling.py
@@ -264,6 +264,7 @@ def start_sub_update(self, sub, control_signal):
             if sub_control_signal is None:
                 sub_control_signal = {}
 
+            # TODO: update schedule, not control signal
             if 'net_power' not in sub_control_signal:
                 sub_control_signal['net_power'] = self.total_p_kw
             if isinstance(sub, Battery) and 'pv_power' not in sub_control_signal: