Merge pull request #989 from NREL/document-outputs

RTD reorganization

.github/workflows/config.yml

@@ -20,9 +20,6 @@ jobs:
       - name: Install gems and software
         run: |
           rm -f Gemfile.lock && bundle install
-          sudo apt update
-          sudo apt-get install -y wget unzip libxml2-utils python3-lxml python3-pip
-          sudo pip3 install sphinx sphinx-rtd-theme
 
       - name: Run integrity checks for all projects
         run: |
@@ -42,17 +39,6 @@ jobs:
           path: resources/buildstock.csv
           name: samples
 
-      - name: Build documentation
-        run: |
-          cd docs/read_the_docs
-          make html SPHINXOPTS="-W --keep-going -n"
-
-      - name: Save Docs
-        uses: actions/upload-artifact@v2
-        with:
-          name: documentation
-          path: docs/read_the_docs/_build/html/
-
   analysis-tests:
     runs-on: ubuntu-latest
     container:
@@ -89,7 +75,7 @@ jobs:
 
       - name: Run buildstockbatch
         run: |
-          pip install git+https://github.com/NREL/buildstockbatch.git@develop
+          pip install git+https://github.com/NREL/buildstockbatch.git@v2022.10.1
           
           buildstock_docker project_national/national_baseline.yml
           buildstock_docker project_testing/testing_baseline.yml
@@ -128,6 +114,13 @@ jobs:
             upgrades
           name: results
 
+      - name: Upload output files
+        uses: actions/upload-artifact@v2
+        with:
+          path: |
+            outputs
+          name: outputs
+
       - name: Upload buildstockbatch results
         uses: actions/upload-artifact@v2
         with:
@@ -252,6 +245,12 @@ jobs:
         with:
           ref: ${{ github.head_ref }}
 
+      - name: Install gems and software
+        run: |
+          sudo apt update
+          sudo apt-get install -y wget unzip libxml2-utils python3-lxml python3-pip
+          sudo pip3 install sphinx sphinx-rtd-theme
+
       - name: Download feature samples
         uses: actions/download-artifact@v2
         with:
@@ -264,6 +263,12 @@ jobs:
           path: results
           name: results
 
+      - name: Download output files
+        uses: actions/download-artifact@v2
+        with:
+          path: outputs
+          name: outputs
+
       - name: Commit latest results
         shell: bash        
         run: |
@@ -274,6 +279,7 @@ jobs:
           cp -r results/baseline/timeseries/results*.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
           git add test/base_results
           git status
           if [[ $(git diff --cached --exit-code) ]]; then
@@ -283,3 +289,14 @@ 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@v2
+        with:
+          name: documentation
+          path: docs/read_the_docs/_build/html/

docs/read_the_docs/source/advanced_tutorial/index.rst

@@ -1,7 +1,7 @@
 .. _advanced_tutorial:
 
 Advanced Tutorial
-#################
+=================
 
 This advanced tutorial describes the process for developing residential measures and testing residential building models. Reasons for wanting to develop residential measures include: customizing any of the existing residential modeling algorithms or adding new technology models.
 

docs/read_the_docs/source/advanced_tutorial/installer_setup.rst

@@ -1,7 +1,7 @@
 Installer Setup
 ===============
 
-After you have downloaded the OpenStudio installer, you may want to install Ruby (2.7.2). This will allow you to execute rake tasks contained in the `Rakefile <https://github.com/NREL/resstock/blob/develop/Rakefile>`_. Follow the instructions below for :ref:`windows-setup` or :ref:`mac-setup`.
+After you have downloaded the OpenStudio installer, you may want to optionally install Ruby (2.7.2). This will allow you to execute rake tasks contained in the `Rakefile <https://github.com/NREL/resstock/blob/develop/Rakefile>`_. Follow the instructions below for :ref:`windows-setup` or :ref:`mac-setup`.
 
 .. _windows-setup:
 

docs/read_the_docs/source/advanced_tutorial/tasks.rst

@@ -70,7 +70,7 @@ Run ``openstudio tasks.rb download_weather`` to download available EPW weather f
 Rakefile
 --------
 
-Once you have completed instructions found in :doc:`installer_setup`, you can then use the `Rakefile <https://github.com/NREL/resstock/blob/develop/Rakefile>`_ contained at the top level of this repository. You will run rake task(s) for :ref:`performing integrity checks on project inputs <integrity-checks>`.
+Once you have completed instructions found in :doc:`installer_setup`, you can then use the `Rakefile <https://github.com/NREL/resstock/blob/develop/Rakefile>`_ contained at the top level of this repository. You can run rake task(s) for :ref:`performing integrity checks on project inputs <integrity-checks>` as well as executing various tests.
 
 Run ``rake -T`` to see the list of possible rake tasks. The ``-T`` is replaced with the chosen task.
 

docs/read_the_docs/source/index.rst

@@ -23,3 +23,4 @@ ResStock Documentation
    tutorial/index
    advanced_tutorial/index
    upgrade_scenario_config
+   outputs/index

docs/read_the_docs/source/outputs/default_outputs.rst

@@ -0,0 +1,48 @@
+.. _default_outputs:
+
+Default Outputs
+===============
+
+The default set of outputs include housing characteristics, annual simulation outputs, and upgrade cost information.
+
+Housing Characteristics
+***********************
+
+Default characteristics include sampled properties for each dwelling unit.
+
+.. csv-table::
+   :file: ../../../../test/base_results/outputs/characteristics.csv
+
+Simulation Output
+*****************
+
+Default annual simulation outputs include energy consumptions (total, by fuel, and by end use), hot water uses, building loads, unmet hours, and peak building electricity/loads.
+
+See the OpenStudio-HPXML Workflow Outputs section on `Annual Outputs <https://openstudio-hpxml.readthedocs.io/en/latest/workflow_outputs.html#annual-outputs>`_ for more information about annual outputs.
+
+.. csv-table::
+   :file: ../../../../test/base_results/outputs/simulation_outputs.csv
+
+.. _upgrade-costs:
+
+Upgrade Costs
+*************
+
+Upgrade cost multipliers include:
+
+.. csv-table::
+   :file: ../../../../test/base_results/outputs/cost_multipliers.csv
+
+Other upgrade cost information includes:
+
+.. list-table::
+
+   * - upgrade_costs.option_<#>_name
+   * - upgrade_costs.option_<#>_cost_usd
+   * - upgrade_costs.option_<#>_lifetime_yrs
+   * - upgrade_costs.upgrade_cost_usd
+
+where <#> represents any of the defined option numbers.
+See :doc:`../upgrade_scenario_config` for more information.
+
+Note that the name, cost, and lifetime information will only be populated when applicable for a given upgrade option (i.e., when the apply logic evaluates as true).

docs/read_the_docs/source/outputs/index.rst

@@ -0,0 +1,12 @@
+.. _available_outputs:
+
+Available Outputs
+=================
+
+ResStock generates a default set of housing characteristics, simulation output, and upgrade cost outputs.
+ResStock optionally generates outputs related to timeseries data, component loads, emissions, utility bills, and quantities of interest.
+
+.. toctree::
+
+  default_outputs
+  optional_outputs

docs/read_the_docs/source/outputs/optional_outputs.rst

@@ -0,0 +1,69 @@
+.. _optional_outputs:
+
+Optional Outputs
+================
+
+Optional outputs include annual component loads, emissions, utility bills, and quantities of interest.
+Additionally, timeseries outputs can be requested.
+
+To be generated, some optional outputs need only a single switch enabled (e.g., component loads).
+Others need additional input arguments specified (e.g., emissions, utility bills).
+
+Note that enabling a set of optional outputs will by default generate the entire set.
+For example, requesting emissions outputs will result in columns for totals by fuel *and* by end use.
+There is currently no way to request totals by fuel while excluding totals by end use.
+
+Component Loads
+***************
+
+Component loads represent the estimated contribution of different building components to the annual heating/cooling building loads.
+
+.. csv-table::
+   :file: ../../../../test/base_results/outputs/component_loads.csv
+
+These outputs require that only a single switch is enabled.
+See the `Residential HPXML Workflow Generator <https://buildstockbatch.readthedocs.io/en/latest/workflow_generators/residential_hpxml.html>`_ documentation page (i.e., ``build_existing_model`` section) for more information.
+
+See the OpenStudio-HPXML Workflow Outputs section on `Annual Component Building Loads <https://openstudio-hpxml.readthedocs.io/en/latest/workflow_outputs.html#annual-component-building-loads>`_ for more information about component loads.
+
+Emissions
+*********
+
+Optional emissions outputs include annual total, by fuel, and by end use, for each emissions scenario requested.
+See the `Residential HPXML Workflow Generator <https://buildstockbatch.readthedocs.io/en/latest/workflow_generators/residential_hpxml.html>`_ documentation page (i.e., ``emissions`` section) for more information on how to request emissions outputs by scenario.
+
+See the OpenStudio-HPXML Workflow Outputs section on `Annual Emissions <https://openstudio-hpxml.readthedocs.io/en/latest/workflow_outputs.html#annual-emissions>`_ for more information about annual emissions.
+
+For the example below, the "LRMER_MidCase_15" emissions scenario was requested.
+See the list of available emissions scenario choices at https://github.com/NREL/resstock/tree/develop/resources/data/cambium.
+
+.. csv-table::
+   :file: ../../../../test/base_results/outputs/emissions.csv
+
+Utility Bills
+*************
+
+Optional utility bill outputs include annual fixed and marginal costs (total, by fuel type), and PV credits for electricity, for each utility bill scenario requested.
+See the `Residential HPXML Workflow Generator <https://buildstockbatch.readthedocs.io/en/latest/workflow_generators/residential_hpxml.html>`_ documentation page (i.e., ``utility_bills`` section) for more information on how to request utility bill outputs by scenario.
+
+See the OpenStudio-HPXML Workflow Outputs section on `Utility Bill Outputs <https://openstudio-hpxml.readthedocs.io/en/latest/workflow_outputs.html#utility-bill-outputs>`_ for more information about utility bill outputs.
+
+.. csv-table::
+   :file: ../../../../test/base_results/outputs/utility_bills.csv
+
+Quantities of Interest
+**********************
+
+These outputs require that only a single switch is enabled.
+See the `Residential HPXML Workflow Generator <https://buildstockbatch.readthedocs.io/en/latest/workflow_generators/residential_hpxml.html>`_ documentation page (i.e., ``reporting_measures`` section) for more information on how to request quantities of interest outputs.
+
+.. csv-table::
+   :file: ../../../../test/base_results/outputs/qoi_report.csv
+
+Timeseries
+**********
+
+Specifying any timeseries frequency other than "none" results in, by default, end use consumptions and total loads timeseries output requests.
+See the `Residential HPXML Workflow Generator <https://buildstockbatch.readthedocs.io/en/latest/workflow_generators/residential_hpxml.html>`_ documentation page (i.e., ``simulation_output_report`` section) for more information on how to request various timeseries outputs (or override default requests).
+
+See the OpenStudio-HPXML Workflow Outputs section on `Timeseries Outputs <https://openstudio-hpxml.readthedocs.io/en/latest/workflow_outputs.html#timeseries-outputs>`_ for more information on timeseries outputs.