RTD: instructions for OS-HPXML subtree

docs/technical_development_guide/source/advanced_tutorial/increasing_upgrade_options.rst

@@ -5,8 +5,9 @@ To allow more options per upgrade, increase the value returned by the following
 
 .. code::
 
-  def self.NumApplyUpgradeOptions
-    return 100
-  end
+  module Constants
+    NumApplyUpgradeOptions = 100
+    NumApplyUpgradesCostsPerOption = 2
+  ...
 
-Then run ``openstudio tasks.rb update_measures``. See :doc:`running_tasks` for instructions on how to run tasks.
+Then run ``openstudio tasks.rb update_measures``. See :doc:`running_task_commands` for instructions on how to run tasks.

docs/technical_development_guide/source/advanced_tutorial/index.rst

@@ -3,18 +3,15 @@
 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.
-
-At this point in the tutorial, it is assumed that you have checked out a new branch that is up-to-date with the ``develop`` of the `ResStock <https://github.com/NREL/resstock>`_ repository. Optionally, you may have created a new project folder (i.e., copied an existing project folder) and modified the set of tsv files in its ``housing_characteristics`` folder.
-
-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.
+This advanced tutorial describes the processes for:
 
 .. toctree::
    :maxdepth: 2
 
-   installer_setup
-   running_tasks
-   options_lookup
+   managing_the_repository
+   running_task_commands
+   updating_options_lookup
    increasing_upgrade_options
    upgrade_scenario_config
    heat_pump_upgrades
+

docs/technical_development_guide/source/advanced_tutorial/managing_the_repository.rst

@@ -0,0 +1,98 @@
+Managing the Repository
+=======================
+
+At this point in the tutorial, it is assumed that you have checked out a new branch that is up-to-date with the either the ``develop`` or ``latest-os-hpxml`` branch of the `ResStock <https://github.com/NREL/resstock>`_ repository.
+Note that 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.
+
+ResStock contains a `git subtree <https://www.atlassian.com/git/tutorials/git-subtree>`_ to the `OpenStudio-HPXML <https://github.com/NREL/OpenStudio-HPXML>`_ repository.
+The subtree is located at ``resources/hpxml-measures``, and is basically a direct copy of all the folders and files contained in OpenStudio-HPXML for a particular commit.
+
+When using or testing a specific OpenStudio-HPXML branch, the subtree at ``resources/hpxml-measures`` can be updated using a set of simple commands.
+Files located at ``resources/hpxml-measures`` should typically never be directly edited or modified manually.
+Once ``resources/hpxml-measures`` has been updated, there are a few :ref:`remaining steps<post-git-subtree-steps>` for ensuring ResStock is properly connected to OpenStudio-HPXML.
+
+ResStock's ``develop`` branch generally points to the latest ``master`` branch of OpenStudio-HPXML.
+A standing ``latest-os-hpxml`` branch in ResStock helps to ensure that ResStock stays up-to-date with OpenStudio-HPXML's development.
+The ``latest-os-hpxml`` is periodically merged into ``develop`` using a "Latest OS-HPXML" pull request.
+
+There is a ResStock maintenance task for keeping ``latest-os-hpxml`` up-to-date, and periodically merging its corresponding pull request.
+Other ResStock tasks are developmental in nature and include, e.g.:
+
+- TSV file updates from `resstock-estimation <https://github.com/NREL/resstock-estimation>`_
+- technical documentation updates
+- tests and/or CI config updates
+- core OpenStudio measure updates
+
+Any of these types of updates may or may not relate to or use files contained in the OpenStudio-HPXML ``resources-hpxml-measures`` subtree.
+Depending on how anticipated ResStock changes and updates relate to OpenStudio-HPXML, branching from either ResStock's ``develop`` or ``latest-os-hpxml`` branch may be more appropriate.
+The following describes general guidelines for:
+
+- when to branch from ``develop`` vs. ``latest-os-hpxml``
+- how to keep your branch up-to-date with either ResStock or OpenStudio-HPXML
+- how to eventually merge your branch into ResStock
+
+Using these guidelines should help to ensure a simple and straightforward merging of new ResStock changes and updates.
+
+
+.. _develop_vs_latest_os_hpxml:
+
+``develop`` vs. ``latest-os-hpxml``
+-----------------------------------
+
+Use ``develop`` for the maintenance task of keeping an up-to-date ``latest-os-hpxml`` branch.
+For updating ResStock's ``develop`` branch to point to OpenStudio-HPXML's ``master`` branch, branch from ``develop`` (with branch name ``latest-os-hpxml``), and then enter the following command:
+
+.. code:: bash
+
+  $ openstudio tasks.rb update_resources
+
+See :doc:`running_task_commands` for more information and context about running tasks.
+Executing the ``update_resources`` task will issue the appropriate ``git subtree ...`` command for syncing ResStock with OpenStudio-HPXML's ``master`` branch.
+
+For pulling in and testing a specific OpenStudio-HPXML branch (i.e., that is not the ``master`` branch), create a test branch in ResStock from ``latest-os-hpxml``.
+Then enter the following command:
+
+.. code:: bash
+
+  $ git subtree pull --prefix resources/hpxml-measures https://github.com/NREL/OpenStudio-HPXML.git <branch_or_tag> --squash
+
+where ``<branch_or_tag>`` represents the OpenStudio-HPXML branch (or tag) name to be pulled in and tested.
+
+Note that the previous command essentially mirrors what ``update_resources`` calls, but with a user-specified branch (or tag) name.
+
+TODO
+
+.. _update_branch:
+
+Update branch
+-------------
+
+TODO
+
+.. _merge_branch:
+
+Merge branch
+------------
+
+TODO
+
+.. _post-git-subtree-steps:
+
+Post ``git subtree`` steps
+--------------------------
+
+After pulling a branch of OpenStudio-HPXML into ResStock, a few additional steps are involved:
+
+1. Run ``openstudio tasks.rb update_measures``.
+
+   This applies rubocop auto-correct to measures, updates measure.xml files, and ensures arguments of the ResStockArguments measure reflect BuildResidentialHPXML.
+
+   Although ``update_measures`` has the same name as OpenStudio-HPXML's ``update_measures`` task, it is applied only to ResStock's core measures.
+
+2. Run ``openstudio measures/ResStockArguments/tests/resstock_arguments_test.rb``.
+
+3. Update ``resources/options_lookup.tsv`` with any new ResStockArguments arguments introduced by BuildResidentialHPXML.
+
+4. Update CSV files in the ``resources/data/dictionary`` folder.
+
+   This addresses any input/output data dictionary changes introduced by OpenStudio-HPXML workflow updates.

docs/technical_development_guide/source/advanced_tutorial/running_tasks.rst → docs/technical_development_guide/source/advanced_tutorial/running_task_commands.rst

@@ -1,5 +1,5 @@
-Running Tasks
-=============
+Running Tasks Commands
+======================
 
 Run ``openstudio tasks.rb`` to see available task commands:
 
@@ -32,6 +32,8 @@ Use ``openstudio tasks.rb update_measures`` to apply rubocop auto-correct to mea
   Updating measure.xmls...
   Done.
 
+.. _update-resources:
+
 Update Resources
 ----------------
 
@@ -65,7 +67,8 @@ Run ``openstudio tasks.rb integrity_check_<project_name>``, where ``<project_nam
   Checking for issues with project_national/Usage Level...
   ...
 
-If the integrity check for a given project fails, you will need to update either your tsv files and/or the ``resources/options_lookup.tsv`` file. See :doc:`options_lookup` for information about the ``options_lookup.tsv`` file.
+If the integrity check for a given project fails, you will need to update either your tsv files and/or the ``resources/options_lookup.tsv`` file.
+See :doc:`updating_options_lookup` for information about the ``options_lookup.tsv`` file.
 
 .. download-weather:
 
@@ -81,20 +84,3 @@ Run ``openstudio tasks.rb download_weather`` to download available EPW weather f
   Downloading /files/156/BuildStock_TMY3_FIPS.zip (  2%) 
   Downloading /files/156/BuildStock_TMY3_FIPS.zip (  3%)
   ...
-
-.. rakefile:
-
-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 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.
-
-.. code:: bash
-
-  $ rake -T
-  rake unit_tests:integrity_check_tests     # Run tests for integrity_check_t...
-  rake unit_tests:measure_tests             # Run tests for measure_tests
-  rake unit_tests:project_integrity_checks  # Run tests for project_integrity...
-  rake workflow:analysis_tests              # Run tests for analysis_tests

docs/technical_development_guide/source/advanced_tutorial/options_lookup.rst → docs/technical_development_guide/source/advanced_tutorial/updating_options_lookup.rst

@@ -1,12 +1,12 @@
-Options Lookup
-==============
+Updating Options Lookup
+=======================
 
-The ``options_lookup.tsv`` file, found in the ``resources`` folder, specifies mappings from sampled options into measure arguments.
-For example, if the distribution of cooling system types in ``HVAC Cooling Efficiency.tsv`` has ``Option=AC, SEER 13`` and ``Option=AC, SEER 15``, but you want to include a ``Option=AC, SEER 17`` option, you would add that option as a column and then create a corresponding row in ``options_lookup.tsv``.
-Updates to this file will allow you to avoid hitting the following types of integrity check errors:
+The ``options_lookup.tsv`` file, found in the ``resources`` folder, specifies mappings from sampled options into ResStockArguments measure arguments.
+For example, if the distribution of cooling system types in ``HVAC Cooling Efficiency.tsv`` has ``Option=AC, SEER 13`` and ``Option=AC, SEER 15``, but you want to include a ``Option=AC, SEER 17`` option, you would add that option as a column in ``HVAC Cooling Efficiency.tsv`` and then create a corresponding row in ``options_lookup.tsv``.
+Updates to ``options_lookup.tsv`` will allow you to avoid hitting the following types of integrity check errors:
 
- - :ref:`Could not find parameter and option <could-not-find-parameter-and-option>`
- - :ref:`Required argument not provided <required-argument-not-provided>`
+- :ref:`Could not find parameter and option <could-not-find-parameter-and-option>`
+- :ref:`Required argument not provided <required-argument-not-provided>`
 
 .. _integrity-check-errors:
 

docs/technical_development_guide/source/advanced_tutorial/upgrade_scenario_config.rst

@@ -1,17 +1,23 @@
 Upgrade Scenario Configuration
 ==============================
 
-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.
+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
 ------------
 
-This is a human readable name for the upgrade scenario. Something like, "Replace electric furnaces with Energy Star heat pumps" or "Insulate attics to R-49".
+This is a human readable name for the upgrade scenario.
+Something like, "Replace electric furnaces with Energy Star heat pumps" or "Insulate attics to R-49".
 
 Option <#>
 ----------
 
-In this field we enter the parameter and option combination to be applied. In the upgrade scenario simulations, this option will replace the option for the corresponding parameter in the baseline run. These can be found and referenced in the ``resources/options_lookup.tsv`` file in your local git repository. You can see the most updated version `on github here <https://github.com/NREL/resstock/blob/develop/resources/options_lookup.tsv>`_, but it's recommended to use your local version as it will be synchronized with your project. The file can be opened in a spreadsheet editor like Excel for viewing. 
+In this field we enter the parameter and option combination to be applied.
+In the upgrade scenario simulations, this option will replace the option for the corresponding parameter in the baseline run.
+These can be found and referenced in the ``resources/options_lookup.tsv`` file in your local git repository.
+You can see the most updated version `on github here <https://github.com/NREL/resstock/blob/develop/resources/options_lookup.tsv>`_, but it's recommended to use your local version as it will be synchronized with your project.
+The file can be opened in a spreadsheet editor like Excel for viewing. 
 
 The text to enter in the field will be the Parameter Name followed by the Option Name separated by a pipe character.
 
@@ -24,15 +30,19 @@ The text to enter in the field will be the Parameter Name followed by the Option
 Option <#> Apply Logic
 ----------------------
 
-The apply logic field specifies the conditions under which the option will apply based on the baseline building's options. To specify the condition(s) include one or more ``parameter|option`` pairs from ``options_lookup.tsv``. Multiple option conditions can be joined using the following logical operators. Parentheses may be used as necessary as well.
+The apply logic field specifies the conditions under which the option will apply based on the baseline building's options.
+To specify the condition(s) include one or more ``parameter|option`` pairs from ``options_lookup.tsv``.
+Multiple option conditions can be joined using the following logical operators. Parentheses may be used as necessary as well.
 
 ====== ===========
 ``||`` logical OR
 ``&&`` logical AND
 ``!``  logical NOT
 ====== ===========
 
-A few examples will illustrate. First, lets say we want the apply the option ``Water Heater|Gas Tankless``, but only for water heaters that are worse and also use gas. We would use the following apply logic:
+A few examples will illustrate.
+First, lets say we want the apply the option ``Water Heater|Gas Tankless``, but only for water heaters that are worse and also use gas.
+We would use the following apply logic:
 
 .. code::
 
@@ -44,21 +54,25 @@ Or say we want to apply the upgrade only to houses with 3 car garages that aren'
 
    (!Location Census Division|New England)&&(Geometry Garage|3 Car)
 
-Currently, you can enter up to 25 options per upgrade. To allow additional options per upgrade you would need to update a method defined in a resource file, run a rake task, and update the outputs section for all PAT projects. See :doc:`../advanced_tutorial/increasing_upgrade_options` for more information.
+Currently, you can enter up to 25 options per upgrade.
+To allow additional options per upgrade you would need to update a method defined in a resource file, run a rake task, and update the outputs section for all PAT projects. See :doc:`../advanced_tutorial/increasing_upgrade_options` for more information.
 
 Option <#> Cost <#>
 -------------------
 
-This is the cost of the upgrade. Multiple costs can be entered and each is multiplied by a cost multiplier, described below.
+This is the cost of the upgrade.
+Multiple costs can be entered and each is multiplied by a cost multiplier, described below.
 
 Option <#> Cost <#> Multiplier
 ------------------------------
 
-The cost above is multiplied by this value, which is a function of the building. Since there can be multiple costs (currently 2), this permits both fixed and variable costs for upgrades that depend on the properties of the baseline house.
+The cost above is multiplied by this value, which is a function of the building.
+Since there can be multiple costs (currently 2), this permits both fixed and variable costs for upgrades that depend on the properties of the baseline house.
 
 See the :ref:`upgrade-costs` workflow outputs for a list of all available multiplier types.
 
 Package Apply Logic
 -------------------
 
-This is where to specifiy logic to determine whether the whole package of upgrades is applied (all of the options together). It uses the same format as :ref:`apply-logic`.
+This is where to specifiy logic to determine whether the whole package of upgrades is applied (all of the options together).
+It uses the same format as :ref:`apply-logic`.