Merge pull request #1079 from NREL/develop

v3.1.0 release
NREL · May 26, 2023 · 63c21e4 · 63c21e4
2 parents 51f8784 + e65c23e
commit 63c21e4
Show file tree

Hide file tree

Showing 967 changed files with 244,636 additions and 179,766 deletions.
diff --git a/.github/workflows/config.yml b/.github/workflows/config.yml
@@ -11,13 +11,13 @@ jobs:
   unit-tests:
     runs-on: ubuntu-latest
     container:
-      image: docker://nrel/openstudio:3.5.1
+      image: docker://nrel/openstudio:3.6.1
     steps:
       - uses: actions/checkout@v3
         with:
           ref: ${{ github.head_ref }}
 
-      - name: Install gems and software
+      - name: Install gems
         run: |
           rm -f Gemfile.lock && bundle install
 
@@ -37,12 +37,18 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           path: resources/buildstock.csv
-          name: samples
+          name: feature_samples
+
+      - name: Store code coverage
+        uses: actions/upload-artifact@v3
+        with:
+          path: coverage
+          name: coverage
 
   analysis-tests:
     runs-on: ubuntu-latest
     container:
-      image: docker://nrel/openstudio:3.5.1
+      image: docker://nrel/openstudio:3.6.1
     steps:
       - uses: actions/checkout@v3
         with:
@@ -64,7 +70,7 @@ jobs:
             project_testing/results-Baseline.csv
             project_national/results-AllUpgrades.csv
             project_testing/results-AllUpgrades.csv
-          name: run_analysis
+          name: run_analysis_results_csvs
 
   integration-tests:
     runs-on: ubuntu-latest
@@ -73,15 +79,22 @@ jobs:
         with:
           ref: ${{ github.head_ref }}
 
+      - name: Download and Install OpenStudio
+        run: |
+          wget -q https://github.com/NREL/OpenStudio/releases/download/v3.6.1/OpenStudio-3.6.1+bb9481519e-Ubuntu-20.04-x86_64.deb
+          sudo apt install -y ./OpenStudio-3.6.1+bb9481519e-Ubuntu-20.04-x86_64.deb
+          openstudio openstudio_version
+          which openstudio
+
       - name: Run buildstockbatch
         run: |
-          pip install git+https://github.com/NREL/buildstockbatch.git@v2023.01.0
+          pip install git+https://github.com/NREL/buildstockbatch.git@v2023.05.0
           
-          buildstock_docker project_national/national_baseline.yml
-          buildstock_docker project_testing/testing_baseline.yml
+          buildstock_local project_national/national_baseline.yml
+          buildstock_local project_testing/testing_baseline.yml
           
-          buildstock_docker project_national/national_upgrades.yml
-          buildstock_docker project_testing/testing_upgrades.yml
+          buildstock_local project_national/national_upgrades.yml
+          buildstock_local project_testing/testing_upgrades.yml
 
       - name: Unzip results
         run: |
@@ -97,43 +110,39 @@ jobs:
           tar -xvf project_national/national_upgrades/simulation_output/*.tar.gz -C project_national/national_upgrades/simulation_output
           tar -xvf project_testing/testing_upgrades/simulation_output/*.tar.gz -C project_testing/testing_upgrades/simulation_output
 
-      - name: Run tests
+      - name: Process results
         run: |
-          ruby test/test_bsb_analysis.rb
+          pip install pandas==1.5.3
+          python test/process_bsb_analysis.py
 
-      - name: Process results
+      - name: Run tests
         run: |
-          pip install pandas
-          python test/util.py
+          sudo gem install minitest-reporters
+          sudo gem install simplecov
+          sudo gem install simplecov-html
+          ruby test/test_bsb_analysis.rb
 
       - name: Upload integration results
         uses: actions/upload-artifact@v3
         with:
           path: |
             baseline
             upgrades
-          name: results
-
-      - name: Upload output files
-        uses: actions/upload-artifact@v3
-        with:
-          path: |
-            outputs
-          name: outputs
+          name: feature_results
 
       - name: Upload buildstockbatch results
         uses: actions/upload-artifact@v3
         with:
           path: |
             project_national/national_baseline/results_csvs/results_up00.csv
             project_testing/testing_baseline/results_csvs/results_up00.csv
-            project_national/national_upgrades/results_csvs/results_up14.csv
-            project_testing/testing_upgrades/results_csvs/results_up14.csv
-          name: buildstockbatch
+            project_national/national_upgrades/results_csvs/results_up15.csv
+            project_testing/testing_upgrades/results_csvs/results_up15.csv
+          name: buildstockbatch_results_csvs
 
   compare-tools:
     runs-on: ubuntu-latest
-    needs: [unit-tests, analysis-tests, integration-tests]
+    needs: [analysis-tests, integration-tests]
     steps:
       - uses: actions/checkout@v3
         with:
@@ -143,22 +152,25 @@ jobs:
         uses: actions/download-artifact@v3
         with:
           path: buildstockbatch
-          name: buildstockbatch
+          name: buildstockbatch_results_csvs
 
       - name: Download run_analysis results
         uses: actions/download-artifact@v3
         with:
           path: run_analysis
-          name: run_analysis
+          name: run_analysis_results_csvs
 
       - name: Run tests
         run: |
-          ruby test/test_tools.rb
+          sudo gem install minitest-reporters
+          sudo gem install simplecov
+          sudo gem install simplecov-html
+          ruby test/test_analysis_tools.rb
 
   compare-results:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
-    needs: [unit-tests, analysis-tests, integration-tests]
+    needs: [integration-tests]
     steps:
       - uses: actions/checkout@v3
         with:
@@ -184,18 +196,18 @@ jobs:
         uses: actions/download-artifact@v3
         with:
           path: samples
-          name: samples
+          name: feature_samples
 
       - name: Download feature results
         uses: actions/download-artifact@v3
         with:
           path: results
-          name: results
+          name: feature_results
 
       - name: Compare samples and results
         run: |          
           pip install numpy
-          pip install pandas
+          pip install pandas==1.5.3
           pip install plotly
           pip install kaleido
           
@@ -239,35 +251,42 @@ jobs:
 
   update-results:
     runs-on: ubuntu-latest
-    needs: [unit-tests, analysis-tests, integration-tests]
+    needs: [integration-tests]
     steps:
       - uses: actions/checkout@v3
         with:
           ref: ${{ github.head_ref }}
 
-      - name: Install gems and software
+      - name: Install software
         run: |
+          export DEBIAN_FRONTEND=noninteractive
           sudo apt update
-          sudo apt-get install -y wget unzip libxml2-utils python3-lxml python3-pip
-          sudo pip3 install sphinx sphinx-rtd-theme
+          sudo -E apt-get install -y wget unzip python3-sphinx-rtd-theme
 
       - name: Download feature samples
         uses: actions/download-artifact@v3
         with:
           path: samples
-          name: samples
+          name: feature_samples
 
       - name: Download feature results
         uses: actions/download-artifact@v3
         with:
           path: results
-          name: results
+          name: feature_results
 
-      - name: Download output files
-        uses: actions/download-artifact@v3
+      - name: Build documentation
+        run: |
+          ruby docs/read_the_docs/source/workflow_inputs/create_characteristics_rst.rb
+          ruby docs/read_the_docs/source/workflow_outputs/csv_tables.rb
+          cd docs/read_the_docs
+          make html SPHINXOPTS="-W --keep-going -n"
+
+      - name: Save Docs
+        uses: actions/upload-artifact@v3
         with:
-          path: outputs
-          name: outputs
+          name: documentation
+          path: docs/read_the_docs/_build/html/
 
       - name: Commit latest results
         shell: bash        
@@ -276,11 +295,11 @@ jobs:
           git pull origin $branch_name
           cp -r samples/buildstock*.csv test/base_results/baseline/annual
           cp -r results/baseline/annual/results*.csv test/base_results/baseline/annual
-          cp -r results/baseline/timeseries/results*.csv test/base_results/baseline/timeseries
+          cp -r results/baseline/timeseries/*.csv test/base_results/baseline/timeseries
           cp -r results/upgrades/annual/results*.csv test/base_results/upgrades/annual
-          cp -r results/upgrades/timeseries/results*.csv test/base_results/upgrades/timeseries
-          cp -r outputs/*.csv test/base_results/outputs
+          cp -r results/upgrades/timeseries/*.csv test/base_results/upgrades/timeseries
           git add test/base_results
+          git add docs
           git status
           if [[ $(git diff --cached --exit-code) ]]; then
             git config --global user.email "github-action@users.noreply.github.com"
@@ -289,14 +308,3 @@ jobs:
             echo "Pushing to branch: $branch_name"
             git push -u origin $branch_name
           fi
-
-      - name: Build documentation
-        run: |
-          cd docs/read_the_docs
-          make html SPHINXOPTS="-W --keep-going -n"
-
-      - name: Save Docs
-        uses: actions/upload-artifact@v3
-        with:
-          name: documentation
-          path: docs/read_the_docs/_build/html/
diff --git a/.gitignore b/.gitignore
@@ -8,9 +8,11 @@
 /project_testing/testing_upgrades
 /resources/buildstock.csv
 /project_*/**/*.csv
+!/project_*/resources/source_report.csv
 /project_*/**/*.log
 /weather
 .vscode/
 .DS_Store
 **/.ipynb_checkpoints/*
 **/data/*
+!/resources/data/dictionary/outputs.csv
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,9 @@
+version: 2
+
+sphinx:
+  configuration: docs/read_the_docs/source/conf.py
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.8"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,21 @@
+## ResStock v3.1.0
+###### May 25, 2023 - [Diff](https://github.com/NREL/resstock/compare/v3.0.0...v3.1.0)
+
+Features
+- Include battery modeling capabilities for project_testing ([#1009](https://github.com/NREL/resstock/pull/1009))
+- Ability to check buildstock csv against an options lookup as a command line utility ([#1042](https://github.com/NREL/resstock/pull/1042))
+- Demonstrate new power outage modeling feature using upgrades specified in example project yml files ([#1054](https://github.com/NREL/resstock/pull/1054))
+- Ability to specify a "sample_weight" column in the precomputed buildstock.csv ([#1056](https://github.com/NREL/resstock/pull/1056))
+- Add descriptions to the housing characteristics ([#1069](https://github.com/NREL/resstock/pull/1069))
+- Connect ASHP to optional capacity retention temperature and fraction arguments (that already exist for MSHP) ([#1071](https://github.com/NREL/resstock/pull/1071))
+- Add data dictionary files for describing various outputs. Use these files to (1) check against integration test results, and (2) generate documentation tables ([#1058](https://github.com/NREL/resstock/pull/1058))
+- OS-HPXML now supports use of optional heat pump capacity retention temperature and fraction arguments (applicable to both ASHP and MSHP) ([#1072](https://github.com/NREL/resstock/pull/1072))
+- Update to OpenStudio v3.6.1 ([#1076](https://github.com/NREL/resstock/pull/1076))
+
+Fixes
+- Pulls in upstream OS-HPXML fix related to [avoiding possible OpenStudio temporary directory collision](https://github.com/NREL/OpenStudio-HPXML/pull/1316) causing random errors ([#1054](https://github.com/NREL/resstock/pull/1054))
+- Pulls in upstream OS-HPXML fix related to [falling back to a WWR calculation when window placement fails](https://github.com/NREL/OpenStudio-HPXML/pull/1385) causing errors fitting windows ([#1076](https://github.com/NREL/resstock/pull/1076))
+
 ## ResStock v3.0.0
 ###### February 3, 2023 - [Diff](https://github.com/NREL/resstock/compare/v2.5.0...v3.0.0)
 
@@ -31,7 +49,7 @@ Fixes
 - Rename sources subfolders so all tsv_makers can be imported as packages ([#959](https://github.com/NREL/resstock/pull/959))
 - Fix heating and cooling auto-season inputs ([#975](https://github.com/NREL/resstock/pull/975))
 - Remove Void from dependency columns in TSVs and update tests.([#981](https://github.com/NREL/resstock/pull/981))
-- Update low-sample downscaling logic to use raw source_weight, which leads to minor changes to Geometry Floor Area and HVAC Partial Sapce Conditioning ([#982](https://github.com/NREL/resstock/pull/982))
+- Update low-sample downscaling logic to use raw source_weight, which leads to minor changes to Geometry Floor Area and HVAC Partial Space Conditioning ([#982](https://github.com/NREL/resstock/pull/982))
 
 ## ResStock v2.5.0
 ###### February 9, 2022 - [Diff](https://github.com/NREL/OpenStudio-BuildStock/compare/v2.4.0...v2.5.0)

diff --git a/README.md b/README.md
@@ -10,14 +10,14 @@ The `develop` branch is under active development. Find the latest release [here]
 
 This repository contains:
 
-- [Housing characteristics of the U.S. residential building stock](https://github.com/NREL/resstock/tree/main/project_national/housing_characteristics), in the form of conditional probability distributions stored as tab-separated value (.tsv) files. A visualization of the dependency structure can be found [here](https://htmlpreview.github.io/?https://github.com/NREL/resstock/blob/main/project_national/util/dependency_wheel/dep_wheel.html)
+- [Housing characteristics of the U.S. residential building stock](https://github.com/NREL/resstock/tree/main/project_national/housing_characteristics), in the form of conditional probability distributions stored as tab-separated value (.tsv) files. Comments at the bottom of each file document data sources and assumptions for each.
 - [A library of housing characteristic "options"](https://github.com/NREL/resstock/blob/main/resources/options_lookup.tsv) that translate high-level characteristic parameters into arguments for OpenStudio measures, and which are referenced by the housing characteristic .tsv files and building energy upgrades defined in project definition files
 - Project definition files:
   - v2.3.0 and later: [buildstockbatch YML files openable in any text editor](https://github.com/NREL/resstock/blob/main/project_national/national_baseline.yml)
   - v2.2.5 and prior: [Project folder openable in PAT](https://github.com/NREL/resstock/tree/v2.2.5/project_singlefamilydetached)
 - Unit-level OpenStudio Measures for automatically constructing OpenStudio Models of each representative dwelling unit model:
   - v3.0.0 and later: [OpenStudio-HPXML Measures](https://github.com/NREL/resstock/tree/main/resources/hpxml-measures)
-  - v2.5.0 and prior: [OpenStudio Measures](https://github.com/NREL/resstock/tree/main/resources/measures)
+  - v2.5.0 and prior: [OpenStudio Measures](https://github.com/NREL/resstock/tree/v2.5.0/resources/measures)
 - [Higher-level OpenStudio Measures](https://github.com/NREL/resstock/tree/main/measures) for controlling simulation inputs and outputs
 
 This repository does not contain software for running ResStock simulations, which can be found as follows:

diff --git a/docs/read_the_docs/source/advanced_tutorial/index.rst b/docs/read_the_docs/source/advanced_tutorial/index.rst
@@ -10,10 +10,10 @@ At this point in the tutorial, it is assumed that you have checked out a new bra
 If your changes are intended to be merged into the ``develop`` branch of the `ResStock <https://github.com/NREL/resstock>`_ repository, a pull request review is required.
 
 .. toctree::
+   :maxdepth: 2
 
-   modifying_probability_distributions
-   writing_housing_characteristics
    installer_setup
    tasks
    options_lookup
-   increasing_upgrade_options
+   increasing_upgrade_options
+   upgrade_scenario_config
diff --git a/...e_docs/source/upgrade_scenario_config.rst → ...nced_tutorial/upgrade_scenario_config.rst b/...e_docs/source/upgrade_scenario_config.rst → ...nced_tutorial/upgrade_scenario_config.rst
@@ -1,7 +1,7 @@
 Upgrade Scenario Configuration
 ==============================
 
-There is quite a bit more flexibility and capability in defining an upgrade scenario than was discussed in the :ref:`tutorial <tutorial-apply-upgrade>`. Here we will go through each field in the **Apply Upgrade** measure and discuss how it can be used to build more complicated real-life scenarios for upgrades.
+There is quite a bit more flexibility and capability in defining an upgrade scenario than was discussed in the :ref:`basic tutorial <tutorial-apply-upgrade>`. Here we will go through each field in the **Apply Upgrade** measure and discuss how it can be used to build more complicated real-life scenarios for upgrades.
 
 Upgrade Name
 ------------

diff --git a/...the_docs/source/tutorial/architecture.rst → ...cs/source/basic_tutorial/architecture.rst b/...the_docs/source/tutorial/architecture.rst → ...cs/source/basic_tutorial/architecture.rst
@@ -22,7 +22,7 @@ See :doc:`run_project` for more information about running ResStock analyses.
 Sampling
 --------
 
-To run the sampling script yourself, from the command line execute, e.g. ``ruby resources/run_sampling.rb -p project_national -n 10000 -o buildstock.csv``, and a file ``buildstock.csv`` will be created in the ``resources`` directory. 
+To run the sampling script yourself, from the command line execute, e.g. ``openstudio resources/run_sampling.rb -p project_national -n 10000 -o buildstock.csv``, and a file ``buildstock.csv`` will be created in the ``resources`` directory.
 
 If a custom ``buildstock.csv`` file is located in a project's ``housing_characteristics`` directory when you run the project, it will automatically be used to generate simulations. If it’s not found, the sampling will be run automatically to create one. For each datapoint, the measure will then look up its building description from the sampled csv.
 
@@ -136,7 +136,7 @@ They contribute to the generation of the model.
   Also, we'll give the upgrade scenario a name: "Triple-Pane Windows" and a cost of $40/ft\ :superscript:`2` of window area by entering the number in **Option 1 Cost Value** and selecting "Window Area (ft^2)" for **Option 1 Cost Multiplier**.
   Like the **downselect logic**, excluded datapoints (i.e., datapoints for which the upgrade does not apply) will result in "completed invalid workflow".
   Note that using no downselect logic will apply the option to all housing units.
-  For a full explanation of how to set up the options and logic surrounding them, see :doc:`../upgrade_scenario_config`.
+  For a full explanation of how to set up the options and logic surrounding them, see :doc:`../advanced_tutorial/upgrade_scenario_config`.
 
 **HPXMLtoOpenStudio**
 

diff --git a/docs/read_the_docs/source/tutorial/index.rst → ..._the_docs/source/basic_tutorial/index.rst b/docs/read_the_docs/source/tutorial/index.rst → ..._the_docs/source/basic_tutorial/index.rst
@@ -1,11 +1,11 @@
-.. _tutorial:
+.. _basic_tutorial:
 
-Tutorial
-========
+Basic Tutorial
+==============
 
 .. toctree::
+   :maxdepth: 2
 
    installation
    architecture
    run_project
-   conclusion