Features to support OCHRE workflow in ResStock

.github/workflows/tests.yml

@@ -7,14 +7,21 @@ on:
     # Run on all pull requests
     types: [opened, synchronize, reopened]
 
+# Add concurrency to cancel in-progress jobs when a new commit is pushed to the PR
+# This avoids CI jobs "stacking up" for the same PR
+concurrency:
+  # Cancel in-progress runs when a new workflow with the same concurrency group is queued
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.11"]
 
     steps:
       - name: Checkout repository
@@ -29,11 +36,30 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -e .
-          pip install pytest pytest-cov
+          pip install pytest pytest-cov pytest-xdist
+
+      - name: Generate OCHRE golden results
+        if: matrix.os == 'macos-latest'
+        run: python test/resstock_golden/generate_ochre_result.py
 
       - name: Run tests
         run: |
-          pytest test/ -v --tb=short --cov=ochre --cov-report=xml --cov-report=term-missing
+          pytest test/ -v --tb=short -n auto --cov=ochre --cov-report=xml --cov-report=term-missing ${{ matrix.os != 'macos-latest' && '-m "not golden"' || '' }}
+
+      - name: Compare OCHRE vs EnergyPlus
+        if: matrix.os == 'macos-latest'
+        run: python test/resstock_golden/compare_ochre_and_eplus.py
+
+      - name: Commit comparison CSVs
+        if: matrix.os == 'macos-latest' && github.event_name == 'pull_request'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git fetch origin ${{ github.head_ref }}
+          git checkout -B ${{ github.head_ref }} FETCH_HEAD
+          git add test/resstock_golden/comparison/
+          git diff --cached --quiet || git commit -m "Update EPlus comparison CSVs"
+          git push origin ${{ github.head_ref }}
 
       - name: Upload coverage to Codecov
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
@@ -59,7 +85,7 @@ jobs:
       - name: Install linting tools
         run: |
           python -m pip install --upgrade pip
-          pip install ruff
+          pip install -e ".[dev]"
 
       - name: Run ruff linter
         run: ruff check . --output-format=github

.gitignore

@@ -1,5 +1,6 @@
 *.pyc
 *.log
+*.rej
 .DS_Store
 
 .idea/
@@ -12,6 +13,10 @@ dist/
 docs/_build
 *.egg-info/
 *.code-workspace
-
+.history
 ochre/defaults/Input Files/OCHRE*
-.history
+test/outputs/
+test/resstock_golden/ochre_result/bldg*/
+test/resstock_golden/ochre_result/ochre_annual_result_new.csv
+test_run/
+uv.lock

changelog.md

@@ -1,5 +1,13 @@
 ## OCHRE Changelog
 
+### OCHRE v0.9.4
+- Added ResStock output mode producing `results_timeseries.csv` and `results_annual.csv`
+  [#167](https://github.com/NREL/OCHRE/issues/167)
+- Added output registry and verbosity-based output control system
+- Added CLI options for `--output_format` and `--export_res`
+- Added EV and PV parsing from dedicated HPXML sections (Vehicles, Photovoltaics)
+- Narrowed Python version requirement
+
 ### OCHRE v0.9.3
 - Allow 120V (aka low power) heat pump water heaters
 - Applied ruff code formatting to entire codebase

docs/source/InputsAndArguments.rst

@@ -177,6 +177,8 @@ The table below lists the optional arguments for creating a ``Dwelling`` model.
 +---------------------------+------------------------+-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
 | ``export_res``            | ``datetime.timedelta`` | None (saves files at end of simulation only)    | Saves intermediate time series results to files at the given simulation interval                                          |
 +---------------------------+------------------------+-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
+| ``output_format``         | string                 | ``ochre``                                       | Output format: ``ochre`` (default) or ``resstock``. See :ref:`resstock-output` for details.                               |
++---------------------------+------------------------+-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
 | ``save_results``          | boolean                | True if ``verbosity > 0``                       | Save results files, including time series files, metrics file, OCHRE schedule file, and status file                       |
 +---------------------------+------------------------+-------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
 | ``save_args_to_json``     | boolean                | False                                           | Save all input arguments to json file, including user defined arguments                                                   |

docs/source/Outputs.rst

@@ -358,6 +358,75 @@ The ``verbosity`` will also impact the print statements provided during the
 simulation. Setting ``verbosity >= 3`` will allow most print statements to be
 written.
 
+.. _resstock-output:
+
+ResStock Output Format
+----------------------
+
+.. note::
+
+   ResStock OCHRE support is currently available on the
+   ``sdr_2025_ochre_support`` branch of ResStock.
+
+When ``output_format`` is set to ``resstock``, OCHRE produces output files
+compatible with the ResStock analysis workflow instead of the default OCHRE
+output files. This mode generates two files:
+
+- ``results_timeseries.csv``: Time series results with ResStock-compatible
+  column names and units. Uses a two-header-row format (column names and units)
+  and supports incremental append via ``export_res``. This format is also
+  compatible with `DView <https://github.com/NREL/wex/wiki/DView>`_, NREL's
+  time-series data viewer.
+
+- ``results_annual.csv``: Annual energy totals by end use in MBtu.
+
+OCHRE output columns are mapped to ResStock column names using a crosswalk CSV
+(``ochre/defaults/resstock_ochre_crosswalk.csv``). Unit conversions are applied
+automatically (e.g., kW to kWh, Celsius to Fahrenheit, W to kBtu).
+
+Known Limitations
+^^^^^^^^^^^^^^^^^
+
+OCHRE models a subset of what ResStock/EnergyPlus covers. The crosswalk CSV
+indicates which ResStock metrics have an OCHRE equivalent (rows with a blank
+OCHRE column are not populated). Key limitations are summarized below.
+
+**Unsupported end uses.** The following equipment types are not modeled in OCHRE
+and their ResStock columns will be blank:
+
+- Dehumidifier
+- Whole house fan
+- Solar thermal pump
+- Mechanical ventilation precooling/preheating
+
+**Partial equipment support.** Some equipment is modeled but with constraints:
+
+- **PV**: Only one PV system is parsed from HPXML. Homes with panels on
+  multiple roof orientations will only use the first system
+  (`#223 <https://github.com/NatLabRockies/OCHRE/issues/223>`_).
+- **Electric vehicle**: Only one vehicle is parsed. Additional vehicles in the
+  HPXML Vehicles section are ignored.
+- **Home battery**: OCHRE has a Battery equipment model, but battery inputs are
+  not yet parsed from HPXML
+  (`#224 <https://github.com/NatLabRockies/OCHRE/issues/224>`_).
+
+**Unmapped ResStock metric categories.** The following categories of ResStock
+output columns are not currently populated by OCHRE:
+
+- **Emissions**: CO2e emissions calculations are not implemented.
+- **Weather**: Only drybulb temperature is mapped. Wetbulb, relative humidity,
+  wind speed, and solar radiation are not yet populated from the weather file
+  (`#222 <https://github.com/NatLabRockies/OCHRE/issues/222>`_).
+- **Peak electricity**: Winter, summer, and annual peak metrics.
+- **Alternative fuels**: End uses for propane, fuel oil, coal, wood cord, and
+  wood pellets.
+- **HVAC design**: Design loads, capacities, and design temperatures.
+- **Electrical panel**: Breaker space counts and panel load metrics.
+- **Hot water volumes**: Clothes washer, dishwasher, fixtures, and distribution
+  waste volumes.
+
+See the crosswalk CSV for the complete column-by-column mapping.
+
 .. _all-metrics:
 
 All Metrics

ochre/Dwelling.py

@@ -11,6 +11,7 @@
     nested_update,
     update_equipment_properties,
     save_json,
+    ResStockOutput,
 )
 from ochre.Models import Envelope
 from ochre.Equipment import (
@@ -72,10 +73,17 @@ def __init__(self, metrics_verbosity=3, save_schedule_columns=None, save_args_to
                 ochre_schedule_file = os.path.join(self.output_path, self.name + "_schedule" + extn)
             else:
                 ochre_schedule_file = None
+
+            # ResStock output format: encapsulated in ResStockOutput
+            if self.output_format == "resstock":
+                self._resstock_output = ResStockOutput(self.output_path, self.time_res)
+            else:
+                self._resstock_output = None
         else:
             self.metrics_file = None
             self.hourly_output_file = None
             ochre_schedule_file = None
+            self._resstock_output = None
 
         # Load properties from HPXML file
         properties, weather_station = load_hpxml(**house_args)
@@ -289,42 +297,56 @@ def generate_results(self):
         # See docs for list of results and verbosity levels
         results = super().generate_results()
 
-        if self.verbosity >= 0:
-            results.update(
-                {
-                    "Total Electric Power (kW)": self.total_p_kw,
-                    "Total Reactive Power (kVAR)": self.total_q_kvar,
-                    "Total Gas Power (therms/hour)": self.total_gas_therms_per_hour,
-                }
-            )
-
-        if self.verbosity >= 6:
-            hours_per_step = self.time_res / dt.timedelta(hours=1)
-            results.update(
-                {
-                    "Total Electric Energy (kWh)": self.total_p_kw * hours_per_step,
-                    "Total Reactive Energy (kVARh)": self.total_q_kvar * hours_per_step,
-                    "Total Gas Energy (therms)": self.total_gas_therms_per_hour * hours_per_step,
-                }
-            )
-
-        if self.verbosity >= 2:
-            for end_use, equipment in self.equipment_by_end_use.items():
-                if equipment and any([e.is_electric for e in equipment]):
-                    results[end_use + " Electric Power (kW)"] = sum([e.electric_kw for e in equipment])
-            for end_use, equipment in self.equipment_by_end_use.items():
-                if equipment and any([e.is_gas for e in equipment]):
-                    results[end_use + " Gas Power (therms/hour)"] = sum([e.gas_therms_per_hour for e in equipment])
-        if self.verbosity >= 8:
-            for end_use, equipment in self.equipment_by_end_use.items():
-                if equipment and any([e.is_electric for e in equipment]):
-                    results[end_use + " Reactive Power (kVAR)"] = sum([e.reactive_kvar for e in equipment])
-            results["Grid Voltage (-)"] = self.voltage
+        self.add_output(results, "Total Electric Power (kW)", self.total_p_kw)
+        self.add_output(results, "Total Reactive Power (kVAR)", self.total_q_kvar)
+        self.add_output(results, "Total Gas Power (therms/hour)", self.total_gas_therms_per_hour)
+
+        hours_per_step = self.time_res / dt.timedelta(hours=1)
+        self.add_output(results, "Total Electric Energy (kWh)", self.total_p_kw * hours_per_step)
+        self.add_output(results, "Total Reactive Energy (kVARh)", self.total_q_kvar * hours_per_step)
+        self.add_output(results, "Total Gas Energy (therms)", self.total_gas_therms_per_hour * hours_per_step)
+
+        # End-use level power aggregation
+        for end_use, equipment in self.equipment_by_end_use.items():
+            if equipment and any([e.is_electric for e in equipment]):
+                self.add_output(results, end_use + " Electric Power (kW)", sum([e.electric_kw for e in equipment]))
+        for end_use, equipment in self.equipment_by_end_use.items():
+            if equipment and any([e.is_gas for e in equipment]):
+                self.add_output(
+                    results, end_use + " Gas Power (therms/hour)", sum([e.gas_therms_per_hour for e in equipment])
+                )
+        for end_use, equipment in self.equipment_by_end_use.items():
+            if equipment and any([e.is_electric for e in equipment]):
+                self.add_output(results, end_use + " Reactive Power (kVAR)", sum([e.reactive_kvar for e in equipment]))
+        self.add_output(results, "Grid Voltage (-)", self.voltage)
 
         return results
 
+    def export_results(self):
+        """
+        Export results to file. For ResStock format, converts and writes to
+        results_timeseries.csv instead of ochre.csv.
+        """
+        if self.output_format != "resstock":
+            return super().export_results()
+
+        df = pd.DataFrame(self.results).set_index("Time") if self.results else None
+        self.results.clear()
+
+        if not self.save_results or df is None or self._resstock_output is None:
+            return df
+
+        self._resstock_output.export_chunk(df)
+        return df
+
     def finalize(self, failed=False):
-        # save final results
+        # For ResStock format, we need custom finalization
+        if self._resstock_output:
+            df = pd.DataFrame(self.results).set_index("Time") if self.results else None
+            self.results.clear()
+            return self._resstock_output.finalize(df=df, failed=failed)
+
+        # Standard OCHRE format
         df = super().finalize(failed)
 
         if df is not None:

ochre/Equipment/Battery.py

@@ -24,8 +24,7 @@ class BatteryThermalModel(OneNodeRCModel):
 
     def generate_results(self):
         results = super().generate_results()
-        if self.verbosity >= 7:
-            results[f"{self.name} (C)"] = self.states[0]
+        self.add_output(results, f"{self.name} (C)", self.states[0])
 
         return results
 
@@ -438,16 +437,18 @@ def calculate_degradation(self):
 
     def generate_results(self):
         results = super().generate_results()
-        if self.verbosity >= 3:
-            results[f"{self.end_use} SOC (-)"] = self.soc
-        if self.verbosity >= 7:
-            results[f"{self.end_use} Energy to Discharge (kWh)"] = self.get_kwh_remaining()
-            if self.degradation_states is not None:
-                results[f"{self.end_use} Nominal Capacity (kWh)"] = self.capacity_kwh_nominal
-                results[f"{self.end_use} Actual Capacity (kWh)"] = self.capacity_kwh
-                results[f"{self.end_use} Degradation State Q1"] = self.degradation_states[0]
-                results[f"{self.end_use} Degradation State Q2"] = self.degradation_states[1]
-                results[f"{self.end_use} Degradation State Q3"] = self.degradation_states[2]
+
+        self.add_output(results, f"{self.end_use} SOC (-)", self.soc)
+
+        self.add_output(results, f"{self.end_use} Energy to Discharge (kWh)", self.get_kwh_remaining())
+
+        if self.degradation_states is not None:
+            self.add_output(results, f"{self.end_use} Nominal Capacity (kWh)", self.capacity_kwh_nominal)
+            self.add_output(results, f"{self.end_use} Actual Capacity (kWh)", self.capacity_kwh)
+            self.add_output(results, f"{self.end_use} Degradation State Q1", self.degradation_states[0])
+            self.add_output(results, f"{self.end_use} Degradation State Q2", self.degradation_states[1])
+            self.add_output(results, f"{self.end_use} Degradation State Q3", self.degradation_states[2])
+
         if self.save_ebm_results:
             results.update(self.make_equivalent_battery_model())
 

ochre/Equipment/EV.py

@@ -334,18 +334,21 @@ def make_equivalent_battery_model(self):
     def generate_results(self):
         results = super().generate_results()
 
-        if self.verbosity >= 3:
-            results[f"{self.end_use} SOC (-)"] = self.soc
-            results[f"{self.end_use} Unmet Load (kWh)"] = self.unmet_load
-        if self.verbosity >= 4:
-            results[f"{self.end_use} Parked"] = self.in_event
-        if self.verbosity >= 7:
-            # results[f'{self.end_use} Setpoint Power (kW)'] = self.setpoint_power or 0
-            results[f"{self.end_use} Start Time"] = self.event_start
-            results[f"{self.end_use} End Time"] = self.event_end
-        if self.verbosity >= 7:
-            remaining_charge_minutes = (1 - self.soc) * self.capacity / (self.max_power_ctrl * EV_EFFICIENCY) * 60
-            results[f"{self.end_use} Remaining Charge Time (min)"] = remaining_charge_minutes
+        self.add_output(results, f"{self.end_use} SOC (-)", self.soc)
+
+        self.add_output(results, f"{self.end_use} Unmet Load (kWh)", self.unmet_load)
+
+        self.add_output(results, f"{self.end_use} Parked", self.in_event)
+
+        self.add_output(results, f"{self.end_use} Start Time", self.event_start)
+
+        self.add_output(results, f"{self.end_use} End Time", self.event_end)
+
+        self.add_output(
+            results,
+            f"{self.end_use} Remaining Charge Time (min)",
+            lambda: (1 - self.soc) * self.capacity / (self.max_power_ctrl * EV_EFFICIENCY) * 60,
+        )
 
         if self.save_ebm_results:
             results.update(self.make_equivalent_battery_model())