merge for v0.8.5 (#125)

Merging dev into main for v0.8.5

- [ ] Reference the issue your PR is fixing
- [x] Assign at least 1 reviewer for your PR
- [ ] Test with run_dwelling.py or other script
- [ ] Update documentation as appropriate
- [ ] Update changelog as appropriate

Author: jmaguire1

.gitignore

@@ -4,14 +4,16 @@
 
 .idea/
 .vscode/
-.env
+.venv
 __pycache__/
 src/
 build/
 dist/
+docs/_build
 *.egg-info/
 *.code-workspace
 environment.yml
+requirements.txt
 
 defaults/Input Files/OCHRE*
 outputs/

README.md

@@ -1,15 +1,16 @@
+![OCHRE](docs\source\images\OCHRE-Logo-Horiz-2Color.png)
+
 # OCHRE: The Object-oriented Controllable High-resolution Residential Energy Model
 
-A high-fidelity, high-resolution residential building model with behind-the-meter DERs and flexible load models 
-that integrates with controllers and distribution models in building-to-grid co-simulation platforms. 
+OCHRE™ is a Python-based building energy modeling (BEM) tool designed to model flexible loads in residential buildings. OCHRE includes detailed models and controls for flexible devices including HVAC equipment, water heaters, electric vehicles, solar PV, and batteries. It is designed to run in co-simulation with custom controllers, aggregators, and grid models.
 
 The full documentation for OCHRE can be found at https://ochre-docs-final.readthedocs.io/en/latest/
 
 Contact: [email protected], [email protected], [email protected]
 
 ## Installation
 
-Note that OCHRE requires Python version 3.9 or higher
+Note that OCHRE requires Python version >=3.9 and <3.12
 
 ### Stand-alone Installation
 

bin/run_equipment.py

@@ -81,7 +81,7 @@ def run_water_heater():
     water_draw_magnitude = 12  # L/min
     withdraw_rate = np.random.choice([0, water_draw_magnitude], p=[0.99, 0.01], size=len(times))
     schedule = pd.DataFrame({
-        'Fixtures (L/min)': withdraw_rate,
+        'Water Heating (L/min)': withdraw_rate,
         'Zone Temperature (C)': 20,
         'Mains Temperature (C)': 7,
     }, index=times)

bin/run_external_control.py

@@ -1,48 +1,100 @@
 import datetime as dt
 import pandas as pd
 
-from ochre import Dwelling
+from ochre import Dwelling, CreateFigures
 from bin.run_dwelling import dwelling_args
 
 # Test script to run single Dwelling with constant external control signal
 
-dwelling_args.update({
-    'ext_time_res': dt.timedelta(minutes=60),
-})
+dwelling_args.update(
+    {
+        "time_res": dt.timedelta(minutes=10),
+        "ext_time_res": dt.timedelta(minutes=60),  # for duty cycle control only
+        "Equipment": {
+            "EV": {
+                'vehicle_type': 'BEV',
+                'charging_level': 'Level 2',
+                'mileage': 150,
+            },
+        },
+    }
+)
 
 example_control_signal = {
-    'HVAC Heating': {'Setpoint': 19},  # 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
-    'Battery': {'P Setpoint': -1.0},  # in kW
+    "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
+    "Battery": {
+        # 'P Setpoint': -1.0,  # in kW
+        # "SOC": 0.8,
+        "Self Consumption Mode": True,
+        "Max Import Limit": 1,  # in kW
+        "Max Export Limit": 1,  # in kW
+        # 'Min SOC': 0.2,
+        # 'Max SOC': 0.8,
+    },
+    "EV": {
+        # "Delay": True,
+        "Max Power": 6,
+        "Max SOC": 0.7,
+        # "P Setpoint": 5,
+        # "SOC": 0.6,
+        # "SOC Rate": 0.02,
+    },
 }
 
 
-def run_constant_control_signal(control_signal):
+def run_with_schedule_control():
+    # Create Dwelling model (same as above)
+    dwelling = Dwelling(name="Test House with Controller", **dwelling_args)
+
+    # Get HVAC heater setpoints
+    heater = dwelling.get_equipment_by_end_use('HVAC Heating')
+    setpoints = heater.schedule['HVAC Heating Setpoint (C)']
+
+    # Reduce heating setpoint by 1C from 5-9PM
+    peak_times = setpoints.between_time(dt.time(17, 0, 0), dt.time(21, 0, 0), inclusive='left').index
+    setpoints.loc[peak_times] -= 1
+    heater.reset_time()  # resets the schedule
+
+    # Run simulation
+    dwelling.simulate()
+
+
+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()
+
+    df["EV Electric Power (kW)"].plot()
+    df["EV SOC (-)"].plot()
+    CreateFigures.plt.show()
 
 
 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
@@ -53,7 +105,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')
 
@@ -73,8 +125,9 @@ def run_with_hvac_controller():
             'hour_of_day': t.hour,
             'outdoor_temp': dwelling.envelope.schedule.loc[t, 'Ambient Dry Bulb (C)'],
             'occupancy': dwelling.envelope.schedule.loc[t, 'Occupancy (Persons)'],
-            'heating_setpoint': heater.schedule.loc[t, 'HVAC Heating Setpoint (C)'],  # Original setpoint for current time
-            'cooling_setpoint': cooler.schedule.loc[t, 'HVAC Cooling Setpoint (C)'],  # Original setpoint for current time
+            # Original setpoints for current time
+            'heating_setpoint': heater.schedule.loc[t, 'HVAC Heating Setpoint (C)'],  
+            'cooling_setpoint': cooler.schedule.loc[t, 'HVAC Cooling Setpoint (C)'],
         })
 
         control_signal = get_hvac_controls(**controller_inputs)
@@ -95,7 +148,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
@@ -110,6 +163,7 @@ def run_controls_from_file(control_file):
 
 
 if __name__ == '__main__':
-    # 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_schedule_control()
+    run_constant_control_signal(example_control_signal)
+    # run_with_hvac_controller()
+    # run_controls_from_file(external_control_file='path/to/control_file.csv')

bin/run_fleet.py

@@ -41,7 +41,7 @@ def run_water_heater_fleet(num_water_heaters=5):
         'Tank Height (m)': 1.22,
         'UA (W/K)': 2.17,
         'schedule': pd.DataFrame({
-            'Fixtures (L/min)': withdraw_rate[wh_name],
+            'Water Heating (L/min)': withdraw_rate[wh_name],
             'Zone Temperature (C)': np.random.uniform(15, 18),
             'Mains Temperature (C)': np.random.uniform(5.6, 8.3),
         }, index=times),

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)

changelog.md

@@ -1,5 +1,33 @@
 ## OCHRE Changelog
 
+### Changes from PRs
+
+- Updated PV model to integrate with PVWatts using PySAM v5.0 (not backwards compatible)
+- PV model accepts tilt and azimuth angles from roof boundary in envelope
+- Removed and renamed PV input arguments related to PySAM
+- Changed the units for some outputs related to heat gains/capacity
+- Added controls and optional schedule columns for HVAC, WH, EV, Battery
+- Added HVAC capacity and max capacity controls, ideal mode only
+- Require HVAC duty cycle control for thermostatic mode only
+- Added water heater max power control
+- Added EV max power and max SOC controls
+- Added `equipment_event_file` input for EVs
+- Added OCHREException class to handle errors
+- Added warnings for HVAC and WH heat pumps with low COP
+- Moved default input file path for package installation
+- Replaced setup.py with pyproject.toml
+- Fixed bug with schedule file import using Pandas v2.2
+- 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
+- Fixed bug with accounting for HVAC delivered heat for standalone HVAC runs 
+- Fixed bug with ASHP backup heater units
+- Fixed bug with battery/generator self-consumption controls
+- Fixed bug with WH and battery islanding time metrics
+- Fixed bug with state space model reduction algorithm
+- Fixed syntax warning for Python 3.12
+
 ### OCHRE v0.8.4-beta
 
 - Fixed bug with air infiltration inputs (works with ResStock 3.0 and 3.1, and OS-HPXML 1.6.0)