Merge pull request #1327 from NREL/develop

v3.4.0 release
NREL · Dec 3, 2024 · f2d3720 · f2d3720
2 parents 76afc4a + 0fbef2d
commit f2d3720
Show file tree

Hide file tree

Showing 366 changed files with 254,120 additions and 130,759 deletions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,14 +1,24 @@
 ## Pull Request Description
-
 [description here]
 
+### Related Pull Requests
+[related PRs from different repositories]
+
+### Related Issues
+[What issue(s) is the PR addressing]
+
 ## Checklist
 
-Not all may apply:
+#### Required:
+- [ ] [Technical reference documentation](https://github.com/NREL/resstock/tree/develop/docs/read_the_docs) has been updated
+- [ ] Add to the [changelog_dev.rst file](https://github.com/NREL/resstock/tree/develop/docs/read_the_docs/source/changelog/changelog_dev.rst)
+- [ ] No unexpected regression test changes on CI (comparison artifacts have been checked)
 
+#### Optional (not all items may apply):
 - [ ] Tests (and test files) have been updated
-- [ ] Documentation has been updated
-  - [ ] If related to resstock-estimation, checklist includes [data dictionary](https://github.com/NREL/resstock/tree/develop/resources/data/dictionary), [source report](https://github.com/NREL/resstock/tree/develop/project_national/resources/source_report.csv), [options saturation](https://github.com/NREL/resstock/tree/develop/project_national/resources/options_saturations.csv), [options_lookup](https://github.com/NREL/resstock/blob/develop/resources/options_lookup.tsv).
-- [ ] Add to the [changelog_dev.rst file](https://github.com/NREL/resstock/tree/develop/docs/read_the_docs/source/changelog/changelog_dev.rst)
-- [ ] `openstudio tasks.rb update_measures` has been run
-- [ ] No unexpected regression test changes on CI (checked comparison artifacts)
+- [ ] Supporting resource files have been updated (related to resstock-estimation)
+  - [ ] [data dictionary](https://github.com/NREL/resstock/tree/develop/resources/data/dictionary)
+  - [ ] [source report](https://github.com/NREL/resstock/tree/develop/project_national/resources/source_report.csv)
+  - [ ] [options saturation](https://github.com/NREL/resstock/tree/develop/project_national/resources/options_saturations.csv)
+  - [ ] [options_lookup](https://github.com/NREL/resstock/blob/develop/resources/options_lookup.tsv)
+- [ ] `openstudio tasks.rb update_measures` has been run
diff --git a/.github/workflows/add_to_project.yml b/.github/workflows/add_to_project.yml
@@ -13,7 +13,7 @@ on:
 jobs:
   add-to-project:
     name: Add pull request or issue to project
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - uses: actions/[email protected]
         with:

diff --git a/.github/workflows/config.yml b/.github/workflows/config.yml
@@ -8,15 +8,15 @@ on:
   workflow_dispatch:
 
 env:
-  OPENSTUDIO_VER: "3.8.0"
-  OPENSTUDIO_SHA: "f953b6fcaf"
-  OPENSTUDIO_PLATFORM: "Ubuntu-20.04-x86_64"
-  OPENSTUDIO_EXT: "deb"
-  OPENSTUDIO_URL: "https://github.com/NREL/OpenStudio/releases/download/v3.8.0"
+  OPENSTUDIO_VER: 3.9.0
+  OPENSTUDIO_SHA: c77fbb9569
+  OPENSTUDIO_PLATFORM: Ubuntu-22.04-x86_64
+  OPENSTUDIO_EXT: deb
+  OPENSTUDIO_URL: https://github.com/NREL/OpenStudio/releases/download/v3.9.0
 
 jobs:
   format-files:
-    runs-on: ubuntu-latest    
+    runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v4
         with:
@@ -35,10 +35,10 @@ jobs:
           name: options_lookup
 
   unit-tests:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     needs: [format-files]
     container:
-      image: docker://nrel/openstudio:3.8.0
+      image: docker://nrel/openstudio:3.9.0
     steps:
       - uses: actions/checkout@v4
         with:
@@ -79,10 +79,10 @@ jobs:
           name: coverage
 
   analysis-tests:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     needs: [unit-tests]
     container:
-      image: docker://nrel/openstudio:3.8.0
+      image: docker://nrel/openstudio:3.9.0
     steps:
       - uses: actions/checkout@v4
         with:
@@ -135,13 +135,17 @@ jobs:
           name: run_analysis_results_csvs
 
   integration-tests:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     needs: [unit-tests]
     steps:
       - uses: actions/checkout@v4
         with:
           ref: ${{ github.head_ref }}
 
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
       - name: Download and Install OpenStudio
         run: |
           export OS_DEBFILE="OpenStudio-$OPENSTUDIO_VER+$OPENSTUDIO_SHA-$OPENSTUDIO_PLATFORM.$OPENSTUDIO_EXT"
@@ -211,7 +215,7 @@ jobs:
           ruby test/test_bsb_analysis.rb
 
   compare-tools:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     needs: [analysis-tests, integration-tests]
     steps:
       - uses: actions/checkout@v4
@@ -239,7 +243,7 @@ jobs:
 
   compare-results:
     if: github.event_name == 'pull_request'
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     needs: [integration-tests]
     steps:
       - uses: actions/checkout@v4
@@ -281,37 +285,25 @@ jobs:
           pip install plotly
           pip install kaleido
           
-          mkdir test/base_results/comparisons
-          
-          mkdir test/base_results/comparisons/baseline
-          
-          mkdir test/base_results/comparisons/baseline/annual
-          
-          python test/compare.py -a samples -b base_results/baseline/annual -f samples -e test/base_results/comparisons/baseline/annual
-                    
-          python test/compare.py -a results -b base_results/baseline/annual -f results/baseline/annual -e test/base_results/comparisons/baseline/annual
-          python test/compare.py -a results -af sum -ac build_existing_model.geometry_building_type_recs -x results_output_building_type_sum.csv -b base_results/baseline/annual -f results/baseline/annual -e test/base_results/comparisons/baseline/annual
-          
-          python test/compare.py -a visualize -dc build_existing_model.geometry_building_type_recs -x results_output_building_type.html -b base_results/baseline/annual -f results/baseline/annual -e test/base_results/comparisons/baseline/annual
-          # python test/compare.py -a visualize -dc build_existing_model.geometry_foundation_type -x results_output_foundation_type.html -b base_results/baseline/annual -f results/baseline/annual -e test/base_results/comparisons/baseline/annual
-          # python test/compare.py -a visualize -dc build_existing_model.census_region -x results_output_cr.html -b base_results/baseline/annual -f results/baseline/annual -e test/base_results/comparisons/baseline/annual
-          # python test/compare.py -a visualize -dc build_existing_model.geometry_building_type_recs -ac build_existing_model.census_region -af sum -x results_output_cr_sum.html -b base_results/baseline/annual -f results/baseline/annual -e test/base_results/comparisons/baseline/annual
+          # baseline annual
+          mkdir -p test/base_results/comparisons/baseline/annual
+          python test/compare.py -a samples -b base_results/baseline/annual -f samples -e test/base_results/comparisons/baseline/annual # base_samples.csv, feature_samples.csv
+          python test/compare.py -a results -b base_results/baseline/annual -f results/baseline/annual -e test/base_results/comparisons/baseline/annual # results_characteristics.csv, results_output.csv
+          python test/compare.py -a results -af sum -ac build_existing_model.geometry_building_type_recs -x results_output_building_type_sum.csv -b base_results/baseline/annual -f results/baseline/annual -e test/base_results/comparisons/baseline/annual # results_output_building_type_sum.csv
+          python test/compare.py -a visualize -dc build_existing_model.geometry_building_type_recs -x results_output_building_type.html -b base_results/baseline/annual -f results/baseline/annual -e test/base_results/comparisons/baseline/annual # *.html
           
+          # baseline timeseries
           mkdir test/base_results/comparisons/baseline/timeseries
-                    
-          python test/compare.py -a timeseries -b base_results/baseline/timeseries -f results/baseline/timeseries -e test/base_results/comparisons/baseline/timeseries
-          
-          mkdir test/base_results/comparisons/upgrades
-          
-          mkdir test/base_results/comparisons/upgrades/annual
-                    
-          python test/compare.py -a results -b base_results/upgrades/annual -f results/upgrades/annual -e test/base_results/comparisons/upgrades/annual
+          python test/compare.py -a timeseries -b base_results/baseline/timeseries -f results/baseline/timeseries -e test/base_results/comparisons/baseline/timeseries # cvrmse_nmbe_*.csv
           
-          python test/compare.py -a visualize -x results_output.html -b base_results/upgrades/annual -f results/upgrades/annual -e test/base_results/comparisons/upgrades/annual
+          # upgrades annual
+          mkdir -p test/base_results/comparisons/upgrades/annual
+          python test/compare.py -a results -b base_results/upgrades/annual -f results/upgrades/annual -e test/base_results/comparisons/upgrades/annual # results_output.csv
+          python test/compare.py -a visualize -x results_output.html -b base_results/upgrades/annual -f results/upgrades/annual -e test/base_results/comparisons/upgrades/annual # *.html
           
+          # upgrades timeseries
           mkdir test/base_results/comparisons/upgrades/timeseries
-                    
-          python test/compare.py -a timeseries -b base_results/upgrades/timeseries -f results/upgrades/timeseries -e test/base_results/comparisons/upgrades/timeseries
+          python test/compare.py -a timeseries -b base_results/upgrades/timeseries -f results/upgrades/timeseries -e test/base_results/comparisons/upgrades/timeseries # cvrmse_nmbe_*.csv
 
       - name: Upload comparisons
         uses: actions/upload-artifact@v4
@@ -320,7 +312,7 @@ jobs:
           name: comparisons
 
   update-results:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     needs: [analysis-tests, integration-tests]
     steps:
       - uses: actions/checkout@v4

diff --git a/README.md b/README.md
@@ -18,5 +18,5 @@ This repository contains:
 
 Software for running ResStock simulations:
 
- - [Versions 2.3.0](https://github.com/NREL/resstock/releases/tag/v2.3.0) and later only support the use of [buildstockbatch](https://github.com/NREL/buildstockbatch) for deploying simulations on high-performance or cloud computing. Version 2.3.0 also removed separate projects for single-family detached and multifamily buildings, in lieu of a combined `project_national` representing the U.S. residential building stock. See the [changelog](https://github.com/NREL/resstock/blob/main/CHANGELOG.md) for more details.
+ - [Versions 2.3.0](https://github.com/NREL/resstock/releases/tag/v2.3.0) and later only support the use of [buildstockbatch](https://github.com/NREL/buildstockbatch) for deploying simulations on high-performance or cloud computing. Version 2.3.0 also removed separate projects for single-family detached and multifamily buildings, in lieu of a combined `project_national` representing the U.S. residential building stock. See the [changelogs](https://resstock.readthedocs.io/en/latest/changelog/index.html) for more details.
  - For large-scale production runs of ResStock, it is recommended that buildstockbatch is used. For smaller-scale tests, [`run_analysis.rb`](https://github.com/NREL/resstock/blob/develop/workflow/run_analysis.rb) can be used. Information about the workflow can be found in ResStock's [documentation](https://resstock.readthedocs.io/en/latest/basic_tutorial/run_project.html#using-run-analysis-rb).
diff --git a/docs/read_the_docs/source/changelog/changelog_3_4_0.rst b/docs/read_the_docs/source/changelog/changelog_3_4_0.rst
@@ -0,0 +1,143 @@
+================
+v3.4.0 Changelog
+================
+
+.. changelog::
+    :version: v3.4.0
+    :released: 2024-12-02
+
+    .. change::
+        :tags: software, openstudio, feature
+        :pullreq: 1318
+
+        **Date**: 2024-11-19
+
+        Title:
+        Latest OS-HPXML
+
+        Description:
+        Update to OpenStudio-HPXML 1.9/OpenStudio 3.9/EnergyPlus 24.2.
+
+        OpenStudio-HPXML: `pull request 1883 <https://github.com/NREL/OpenStudio-HPXML/pull/1883>`_
+
+        Assignees: Joe Robertson, Scott Horowitz
+
+
+    .. change::
+        :tags: bugfix, characteristics
+        :pullreq: 1265
+        :tickets: 1236
+
+        **Date**: 2024-09-24
+
+        Title:
+        Fix Hot Water Fixtures multipliers
+
+        Description:
+        Mean-shift hot water usage multipliers distribution by increasing weighted average from 0.8 to 1.0 in Hot Water Fixtures.tsv.
+
+        resstock-estimation: `pull request 420 <https://github.com/NREL/resstock-estimation/pull/420>`_
+
+        Assignees: Lixi Liu
+
+
+    .. change::
+        :tags: workflow, infiltration, bugfix
+        :pullreq: 1257
+
+        **Date**: 2024-08-20
+
+        Title:
+        Air leakage type "unit total"
+
+        Description:
+        Update options_lookup and ResStockArguments to use "unit total" air leakage type instead of the current "unit exterior only" type w/ infiltration adjustment approach.
+        Modeled infiltration for dwelling units now have an upper bound equal to the sampled ACH50 option.
+        Update BuildExistingModel to register adjusted total infiltration ACH50 value.
+
+        Assignees: Joe Robertson
+
+
+    .. change::
+        :tags: characteristics, floor area, bugfix
+        :pullreq: 1301
+        :tickets: 1273
+
+        **Date**: 2024-09-23
+
+        Title:
+        Fix RECS floor area bins
+
+        Description:
+        RECS have been using incorrect floor area bins when assigning some characteristics due to a bug on how floor area bin is calculated. This PR fixes the issue.
+
+        resstock-estimation: `pull request 424 <https://github.com/NREL/resstock-estimation/pull/424>`_
+
+        Assignees: Rajendra Adhikari, Anthony Fontanini
+
+
+    .. change::
+        :tags: workflow, hot water, feature
+        :pullreq: 1282
+
+        **Date**: 2024-09-04
+
+        Title:
+        Latest OS-HPXML
+
+        Description:
+        For hot water end uses OS-HPXML now directly uses equations from https://www.fsec.ucf.edu/en/publications/pdf/fsec-pf-464-15.pdf, that are a function of number of occupants, for operational calculations.
+
+        OpenStudio-HPXML: `pull request 1761 <https://github.com/NREL/OpenStudio-HPXML/pull/1761>`_
+
+        Assignees: Joe Robertson
+
+
+    .. change::
+        :tags: workflow, plug loads, feature
+        :pullreq: 1298
+
+        **Date**: 2024-09-26
+
+        Title:
+        Latest OS-HPXML
+
+        Description:
+        For TV plug loads, we are now using OS-HPXML defaults that directly use equations from RECS 2020 that are a function of number of occupants and conditioned floor area.
+        For operational calculations in general, we are also updating the relationships between number of bedrooms/occupants based on RECS 2020 and disaggregated by building types.
+
+        OpenStudio-HPXML: `pull request 1690 <https://github.com/NREL/OpenStudio-HPXML/pull/1690>`_, `pull request 1775 <https://github.com/NREL/OpenStudio-HPXML/pull/1775>`_
+
+        Assignees: Joe Robertson
+
+
+    .. change::
+        :tags: workflow, hvac, feature
+        :pullreq: 1254
+
+        **Date**: 2024-09-27
+
+        Title:
+        Heating and Cooling Unavailable Days
+
+        Description:
+        The purpose of this PR is to account for dwelling units whose HVAC system (heating/cooling) is unavailable for some number of days during the year (per RECS 2020).
+        Specifically, this PR modifies HVAC heating/cooling seasons using number of unavailable days and BAHSP definition for heating/cooling months.
+
+        resstock-estimation: `pull request 416 <https://github.com/NREL/resstock-estimation/pull/416>`_
+
+        Assignees: Joe Robertson
+
+
+    .. change::
+        :tags: workflow, hvac, feature
+        :pullreq: 1304
+        :tickets: 1303
+
+        **Date**: 2024-11-14
+
+        Title:
+        Assign above-grade height for apartment units
+
+        Description:
+        The purpose of this PR is to set a value in ResStockArguments for apartment units based on the type/size of MF building and where the unit is located (lower, middle, or upper story).
diff --git a/docs/read_the_docs/source/changelog/changelog_dev.rst b/docs/read_the_docs/source/changelog/changelog_dev.rst
@@ -3,5 +3,5 @@ Development Changelog
 =====================
 
 .. changelog::
-    :version: v3.4.0
+    :version: v3.5.0
     :released: pending
diff --git a/docs/read_the_docs/source/changelog/index.rst b/docs/read_the_docs/source/changelog/index.rst
@@ -6,6 +6,7 @@ Changelogs
 .. toctree::
    :titlesonly:
 
+   changelog_3_4_0
    changelog_3_3_0
    changelog_3_2_0
    changelog_3_1_1