From 9d2d66906907db113489b0d86e4c9ccfda798c24 Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Tue, 10 Dec 2024 16:35:41 -0700 Subject: [PATCH 01/10] Remove installer setup docs. --- .../advanced_tutorial/installer_setup.rst | 93 ------------------- .../advanced_tutorial/running_tasks.rst | 19 +--- 2 files changed, 2 insertions(+), 110 deletions(-) delete mode 100644 docs/read_the_docs/source/advanced_tutorial/installer_setup.rst diff --git a/docs/read_the_docs/source/advanced_tutorial/installer_setup.rst b/docs/read_the_docs/source/advanced_tutorial/installer_setup.rst deleted file mode 100644 index c87ff1fd1a..0000000000 --- a/docs/read_the_docs/source/advanced_tutorial/installer_setup.rst +++ /dev/null @@ -1,93 +0,0 @@ -Installer Setup -=============== - -After you have downloaded the OpenStudio installer, you may want to optionally install Ruby (3.2.2). This will allow you to execute rake tasks contained in the `Rakefile `_. Follow the instructions below for :ref:`windows-setup` or :ref:`mac-setup`. - -.. _windows-setup: - -Windows Setup -------------- - -1. Install `Ruby `_ (3.2.2). Follow the installation instructions `here `_ ("Optional - Install Ruby"). -2. Run ``gem install bundler -v 2.4.10``. - -.. note:: - - If you get an error, you may have to issue the following: ``gem sources -r https://rubygems.org/`` followed by ``gem sources -a http://rubygems.org/``. If you still get an error, manually update your gem sources list by including a config file named ".gemrc" in your home directory (.e.g, /c/Users/) with the following contents: - -.. literalinclude:: .gemrc - -3. Download the DevKit (e.g., DevKit-mingw64-64-4.7.2-20130224-1432-sfx.exe). Choose either the 32-bit or 64-bit version depending on which version of Ruby you installed. Run the installer and extract to a directory (e.g., C:\\RubyDevKit). Go to this directory, run ``ruby dk.rb init``, modify the config.yml file as needed, and finally run ``ruby dk.rb install``. -4. Run ``bundle install`` from the resstock directory. (If you get an error, check that ``git`` is in your ``PATH`` and that you are using the correct version of Ruby (3.2.2).) - -.. _mac-setup: - -Mac Setup ---------- - -Install `Homebrew `_ if you don't have it already. - -Run ``brew doctor``. It should give you, among other issues, a list of unexpected dylibs that you'll need to move for this to work such as: - -.. code:: bash - - Unexpected dylibs: - /usr/local/lib/libcrypto.0.9.8.dylib - /usr/local/lib/libcrypto.1.0.0.dylib - /usr/local/lib/libcrypto.dylib - /usr/local/lib/libklcsagt.dylib - /usr/local/lib/libklcskca.dylib - /usr/local/lib/libklcsnagt.dylib - /usr/local/lib/libklcsrt.dylib - /usr/local/lib/libklcsstd.dylib - /usr/local/lib/libklcstr.dylib - /usr/local/lib/libklmspack.0.1.0.dylib - /usr/local/lib/libklmspack.0.dylib - /usr/local/lib/libklmspack.dylib - /usr/local/lib/libssl.0.9.8.dylib - /usr/local/lib/libssl.1.0.0.dylib - /usr/local/lib/libssl.dylib - /usr/local/lib/libz.1.2.5.dylib - /usr/local/lib/libz.1.2.6.dylib - /usr/local/lib/libz.1.dylib - /usr/local/lib/libz.dylib - -Highlight and copy the list (without the header "Unexpected dylibs:"). Run the following commands to move them to another location where they won't interfere. - -.. code:: bash - - mkdir ~/unused_dylibs - pbpaste | xargs -t -I % mv % ~/unused_dylibs - -Install ``rbenv`` and required dependencies. - -.. code:: bash - - brew install openssl libyaml libffi rbenv - -Initialize ``rbenv`` by running the command below and following the instructions to add the appropriate things to your ``~/.bash_profile``. - -.. code:: bash - - rbenv init - -Install the appropriate ruby version. - -.. code:: bash - - cd path/to/repo - rbenv install `cat .ruby-version` - -Add the path to the install ruby libraries top the bottom of your ``~/.bash_profile`` - -.. code:: bash - - echo "export RUBYLIB=/Applications/OpenStudio-3.2.1/Ruby" >> ~/.bash_profile - echo "export ENERGYPLUS_EXE_PATH=\"/Applications/OpenStudio-3.2.1/EnergyPlus/energyplus-9.5.0\"" - -Install bundler and the libraries that bundler installs. - -.. code:: bash - - gem install bundler -v 1.17.1 - bundle install diff --git a/docs/read_the_docs/source/advanced_tutorial/running_tasks.rst b/docs/read_the_docs/source/advanced_tutorial/running_tasks.rst index ec369731b1..9250b2f266 100644 --- a/docs/read_the_docs/source/advanced_tutorial/running_tasks.rst +++ b/docs/read_the_docs/source/advanced_tutorial/running_tasks.rst @@ -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 ---------------- @@ -81,20 +83,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 `_ contained at the top level of this repository. You can run rake task(s) for :ref:`performing integrity checks on project inputs ` 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 From c427d8c0b4f1c10dd254ce02cfa22cf7ee576a1f Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Tue, 10 Dec 2024 16:36:17 -0700 Subject: [PATCH 02/10] Fix code in increasing upgrade options docs. --- .../advanced_tutorial/increasing_upgrade_options.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/read_the_docs/source/advanced_tutorial/increasing_upgrade_options.rst b/docs/read_the_docs/source/advanced_tutorial/increasing_upgrade_options.rst index c29790e720..146b971659 100644 --- a/docs/read_the_docs/source/advanced_tutorial/increasing_upgrade_options.rst +++ b/docs/read_the_docs/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 25 - end + module Constants + NumApplyUpgradeOptions = 25 + NumApplyUpgradesCostsPerOption = 2 + ... Then run ``openstudio tasks.rb update_measures``. See :doc:`running_tasks` for instructions on how to run tasks. From 7d8cbacc11ffa19a231dc96a9ea1324b63fa364f Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Tue, 10 Dec 2024 16:36:32 -0700 Subject: [PATCH 03/10] Add openstudio hpxml docs. --- .../source/advanced_tutorial/index.rst | 2 +- .../advanced_tutorial/openstudio_hpxml.rst | 34 +++++++++++++++++++ .../advanced_tutorial/options_lookup.rst | 4 +-- 3 files changed, 37 insertions(+), 3 deletions(-) create mode 100644 docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst diff --git a/docs/read_the_docs/source/advanced_tutorial/index.rst b/docs/read_the_docs/source/advanced_tutorial/index.rst index dde6b60a56..d9fd7aa47a 100644 --- a/docs/read_the_docs/source/advanced_tutorial/index.rst +++ b/docs/read_the_docs/source/advanced_tutorial/index.rst @@ -12,9 +12,9 @@ If your changes are intended to be merged into the ``develop`` branch of the `Re .. toctree:: :maxdepth: 2 - installer_setup running_tasks options_lookup increasing_upgrade_options upgrade_scenario_config heat_pump_upgrades + openstudio_hpxmls \ No newline at end of file diff --git a/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst b/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst new file mode 100644 index 0000000000..e17593d739 --- /dev/null +++ b/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst @@ -0,0 +1,34 @@ +OpenStudio-HPXML +================ + +ResStock contains a `git subtree `_ to the `OpenStudio-HPXML `_ repository. +The subtree is located at ``resources/hpxml-measures``, and is basically a direct copy of all the files contained in OpenStudio-HPXML. +As OpenStudio-HPXML is updated, ResStock's develop branch is periodically updated to point to the master branch of OpenStudio-HPXML, helping to ensure that ResStock stays up-to-date with OpenStudio-HPXML's development. +It may also be helpful to test an OpenStudio-HPXML branch using a branch of ResStock. +In either case, the subtree at ``resources/hpxml-measures`` can be updated using a set of simple commands. + +.. _latest-os-hpxml: + +For updating ResStock's develop branch to point to OpenStudio-HPXML's master branch, first checkout a ``latest-os-hpxml`` branch, and then enter the following command: + +.. code:: bash + + $ openstudio tasks.rb update_resources + +See :doc:r`running_tasks` for more information and context about running tasks. + +.. _branch-os-hpxml: + +For pulling in any OpenStudio-HPXML branch of choice, first checkout test branch in ResStock. Then enter the following command: + +.. code:: bash + + $ git subtree pull --prefix resources/hpxml-measures https://github.com/NREL/OpenStudio-HPXML.git --squash + +.. _other-updates: + +After pulling a branch of OpenStudio-HPXML into ResStock, a few additional steps are involved: +- manually edit measures/ResStockArguments/measure.rb and run ``openstudio tasks.rb update_measures`` to force the measure.xml to be regenerated. +- update options lookup with any new ResStockArguments arguments +- address any input/output data dictionary updates at ``resources/data/dictionary`` +- TODO diff --git a/docs/read_the_docs/source/advanced_tutorial/options_lookup.rst b/docs/read_the_docs/source/advanced_tutorial/options_lookup.rst index b6c396e03d..344893ddef 100644 --- a/docs/read_the_docs/source/advanced_tutorial/options_lookup.rst +++ b/docs/read_the_docs/source/advanced_tutorial/options_lookup.rst @@ -5,8 +5,8 @@ The ``options_lookup.tsv`` file, found in the ``resources`` folder, specifies ma 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: - - :ref:`Could not find parameter and option ` - - :ref:`Required argument not provided ` +- :ref:`Could not find parameter and option ` +- :ref:`Required argument not provided ` .. _integrity-check-errors: From 94050e3493ec739a98f8287b5df2959d6f2fe668 Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Tue, 10 Dec 2024 20:22:54 -0700 Subject: [PATCH 04/10] Typo. --- docs/read_the_docs/source/advanced_tutorial/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/read_the_docs/source/advanced_tutorial/index.rst b/docs/read_the_docs/source/advanced_tutorial/index.rst index d9fd7aa47a..f97a299724 100644 --- a/docs/read_the_docs/source/advanced_tutorial/index.rst +++ b/docs/read_the_docs/source/advanced_tutorial/index.rst @@ -17,4 +17,4 @@ If your changes are intended to be merged into the ``develop`` branch of the `Re increasing_upgrade_options upgrade_scenario_config heat_pump_upgrades - openstudio_hpxmls \ No newline at end of file + openstudio_hpxml \ No newline at end of file From 50a96678edfab80fbd0c65e2d166722c751e1b16 Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Wed, 11 Dec 2024 14:02:26 -0700 Subject: [PATCH 05/10] Progress on openstudio-hpxml docs. --- .../advanced_tutorial/openstudio_hpxml.rst | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst b/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst index e17593d739..2e092b9699 100644 --- a/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst +++ b/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst @@ -3,23 +3,29 @@ OpenStudio-HPXML ResStock contains a `git subtree `_ to the `OpenStudio-HPXML `_ repository. The subtree is located at ``resources/hpxml-measures``, and is basically a direct copy of all the files contained in OpenStudio-HPXML. -As OpenStudio-HPXML is updated, ResStock's develop branch is periodically updated to point to the master branch of OpenStudio-HPXML, helping to ensure that ResStock stays up-to-date with OpenStudio-HPXML's development. +As OpenStudio-HPXML is updated, ResStock's ``develop`` branch is periodically updated to point to the ``master`` branch of OpenStudio-HPXML, helping to ensure that ResStock stays up-to-date with OpenStudio-HPXML's development. It may also be helpful to test an OpenStudio-HPXML branch using a branch of ResStock. In either case, the subtree at ``resources/hpxml-measures`` can be updated using a set of simple commands. .. _latest-os-hpxml: -For updating ResStock's develop branch to point to OpenStudio-HPXML's master branch, first checkout a ``latest-os-hpxml`` branch, and then enter the following command: +Syncing OpenStudio-HPXML +------------------------ + +For updating ResStock's ``develop`` branch to point to OpenStudio-HPXML's ``master`` branch, branch off of ``develop`` (e.g., with branch name ``latest-os-hpxml``), and then enter the following command: .. code:: bash $ openstudio tasks.rb update_resources -See :doc:r`running_tasks` for more information and context about running tasks. +See :doc:`running_tasks` for more information and context about running tasks. .. _branch-os-hpxml: -For pulling in any OpenStudio-HPXML branch of choice, first checkout test branch in ResStock. Then enter the following command: +Testing OpenStudio-HPXML +------------------------ + +For pulling in and testing a specific OpenStudio-HPXML branch, first create a test branch in ResStock. Then enter the following command: .. code:: bash @@ -27,8 +33,11 @@ For pulling in any OpenStudio-HPXML branch of choice, first checkout test branch .. _other-updates: +Other Updates +------------- + After pulling a branch of OpenStudio-HPXML into ResStock, a few additional steps are involved: -- manually edit measures/ResStockArguments/measure.rb and run ``openstudio tasks.rb update_measures`` to force the measure.xml to be regenerated. +- manually edit measures/ResStockArguments/measure.rb and run ``openstudio tasks.rb update_measures`` to force the measure.xml to be regenerated - update options lookup with any new ResStockArguments arguments - address any input/output data dictionary updates at ``resources/data/dictionary`` - TODO From df45642fe49ba1e9f2a0225027adcc3159f1a965 Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Tue, 7 Jan 2025 10:06:35 -0700 Subject: [PATCH 06/10] Continue updates to new docs page. --- .../advanced_tutorial/openstudio_hpxml.rst | 33 ++++++++++++------- measures/UpgradeCosts/measure.xml | 22 ++----------- 2 files changed, 23 insertions(+), 32 deletions(-) diff --git a/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst b/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst index 2e092b9699..b1340382dd 100644 --- a/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst +++ b/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst @@ -2,10 +2,13 @@ OpenStudio-HPXML ================ ResStock contains a `git subtree `_ to the `OpenStudio-HPXML `_ repository. -The subtree is located at ``resources/hpxml-measures``, and is basically a direct copy of all the files contained in OpenStudio-HPXML. -As OpenStudio-HPXML is updated, ResStock's ``develop`` branch is periodically updated to point to the ``master`` branch of OpenStudio-HPXML, helping to ensure that ResStock stays up-to-date with OpenStudio-HPXML's development. -It may also be helpful to test an OpenStudio-HPXML branch using a branch of ResStock. -In either case, the subtree at ``resources/hpxml-measures`` can be updated using a set of simple commands. +The subtree is located at ``resources/hpxml-measures``, and is basically a direct copy of all the folders and files contained in OpenStudio-HPXML. +As OpenStudio-HPXML is updated, ResStock's ``develop`` branch is periodically updated to point to the latest ``master`` branch of OpenStudio-HPXML, helping to ensure that ResStock stays up-to-date with OpenStudio-HPXML's development. +It may also be helpful to test an OpenStudio-HPXML branch (or tag) using a branch of ResStock. +In both cases, 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 manually edited or modified. + +Once ``resources/hpxml-measures`` has been updated, there are a few other steps for ensuring ResStock is properly connected to OpenStudio-HPXML. .. _latest-os-hpxml: @@ -19,25 +22,31 @@ For updating ResStock's ``develop`` branch to point to OpenStudio-HPXML's ``mast $ openstudio tasks.rb update_resources See :doc:`running_tasks` 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. .. _branch-os-hpxml: Testing OpenStudio-HPXML ------------------------ -For pulling in and testing a specific OpenStudio-HPXML branch, first create a test branch in ResStock. Then enter the following command: +For pulling in and testing a specific OpenStudio-HPXML branch (i.e., that is not the ``master`` branch), first create a test branch in ResStock. +Then enter the following command: .. code:: bash - $ git subtree pull --prefix resources/hpxml-measures https://github.com/NREL/OpenStudio-HPXML.git --squash + $ git subtree pull --prefix resources/hpxml-measures https://github.com/NREL/OpenStudio-HPXML.git --squash + +where ```` 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/tag name. .. _other-updates: -Other Updates -------------- +Other Steps +----------- After pulling a branch of OpenStudio-HPXML into ResStock, a few additional steps are involved: -- manually edit measures/ResStockArguments/measure.rb and run ``openstudio tasks.rb update_measures`` to force the measure.xml to be regenerated -- update options lookup with any new ResStockArguments arguments -- address any input/output data dictionary updates at ``resources/data/dictionary`` -- TODO + +1. Run ``openstudio tasks.rb update_measures``; this applies rubocop auto-correct to measures, updates measure.xml files, and ensures ResStockArguments reflects the latest BuildResidentialHPXML +2. Run ``openstudio measures/ResStockArguments/tests/resstock_arguments_test.rb``; update ``resources/options_lookup.tsv`` with any new ResStockArguments arguments introduced by BuildResidentialHPXML +3. Update files in ``resources/data/dictionary``; this addresses any input/output data dictionary changes diff --git a/measures/UpgradeCosts/measure.xml b/measures/UpgradeCosts/measure.xml index dafbe070db..da26cb0c9b 100644 --- a/measures/UpgradeCosts/measure.xml +++ b/measures/UpgradeCosts/measure.xml @@ -3,8 +3,8 @@ 3.1 upgrade_costs ef51212c-acc4-48d7-9b29-cf2a5c6c4449 - bf069249-d884-4cfd-8579-3b5bc1ff55e5 - 2024-11-08T15:53:04Z + a45a8e07-d2e2-42a3-adf8-da027e8e37cf + 2025-01-07T16:36:06Z B1F14CB4 UpgradeCosts Upgrade Costs @@ -239,24 +239,6 @@ test 083B023F - - in.epw - epw - test - E23378AA - - - in.osm - osm - test - 92AA6A08 - - - in.xml - xml - test - 72608A61 - upgrade_costs_test.rb rb From 3d21db6097693a45b29820b3b90737024836386c Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Thu, 9 Jan 2025 09:13:13 -0700 Subject: [PATCH 07/10] Minor updates to new docs page. --- .../advanced_tutorial/openstudio_hpxml.rst | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst b/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst index b1340382dd..3e05b96682 100644 --- a/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst +++ b/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst @@ -6,14 +6,14 @@ The subtree is located at ``resources/hpxml-measures``, and is basically a direc As OpenStudio-HPXML is updated, ResStock's ``develop`` branch is periodically updated to point to the latest ``master`` branch of OpenStudio-HPXML, helping to ensure that ResStock stays up-to-date with OpenStudio-HPXML's development. It may also be helpful to test an OpenStudio-HPXML branch (or tag) using a branch of ResStock. In both cases, 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 manually edited or modified. +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 other steps for ensuring ResStock is properly connected to OpenStudio-HPXML. .. _latest-os-hpxml: -Syncing OpenStudio-HPXML ------------------------- +Syncing w/latest +---------------- For updating ResStock's ``develop`` branch to point to OpenStudio-HPXML's ``master`` branch, branch off of ``develop`` (e.g., with branch name ``latest-os-hpxml``), and then enter the following command: @@ -26,8 +26,8 @@ Executing the ``update_resources`` task will issue the appropriate ``git subtree .. _branch-os-hpxml: -Testing OpenStudio-HPXML ------------------------- +Testing a branch +---------------- For pulling in and testing a specific OpenStudio-HPXML branch (i.e., that is not the ``master`` branch), first create a test branch in ResStock. Then enter the following command: @@ -38,15 +38,15 @@ Then enter the following command: where ```` 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/tag name. +Note that the previous command essentially mirrors what ``update_resources`` calls, but with a user-specified branch (or tag) name. -.. _other-updates: +.. _other-steps: -Other Steps +Other 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 ResStockArguments reflects the latest BuildResidentialHPXML +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 2. Run ``openstudio measures/ResStockArguments/tests/resstock_arguments_test.rb``; update ``resources/options_lookup.tsv`` with any new ResStockArguments arguments introduced by BuildResidentialHPXML -3. Update files in ``resources/data/dictionary``; this addresses any input/output data dictionary changes +3. Update CSV files in the ``resources/data/dictionary`` folder; this addresses any input/output data dictionary changes introduced by OpenStudio-HPXML workflow updates From ab1a6c087e0aef06c2d9bf8d7990f3081cf2c3e0 Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Thu, 16 Jan 2025 15:16:09 -0700 Subject: [PATCH 08/10] Split 1 other step into 2. --- .../source/advanced_tutorial/openstudio_hpxml.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst b/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst index 3e05b96682..05943b115a 100644 --- a/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst +++ b/docs/read_the_docs/source/advanced_tutorial/openstudio_hpxml.rst @@ -48,5 +48,6 @@ Other 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 -2. Run ``openstudio measures/ResStockArguments/tests/resstock_arguments_test.rb``; update ``resources/options_lookup.tsv`` with any new ResStockArguments arguments introduced by BuildResidentialHPXML -3. Update CSV files in the ``resources/data/dictionary`` folder; this addresses any input/output data dictionary changes introduced by OpenStudio-HPXML workflow updates +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 From 279f5758090770969503b5b6c45a81821599613f Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Wed, 22 Jan 2025 16:12:21 -0700 Subject: [PATCH 09/10] Try reformatting new docs page as Branching and Merging. --- .../branching_and_merging.rst | 105 ++++++++++++++++++ .../source/advanced_tutorial/index.rst | 2 +- .../advanced_tutorial/openstudio_hpxml.rst | 53 --------- 3 files changed, 106 insertions(+), 54 deletions(-) create mode 100644 docs/technical_development_guide/source/advanced_tutorial/branching_and_merging.rst delete mode 100644 docs/technical_development_guide/source/advanced_tutorial/openstudio_hpxml.rst diff --git a/docs/technical_development_guide/source/advanced_tutorial/branching_and_merging.rst b/docs/technical_development_guide/source/advanced_tutorial/branching_and_merging.rst new file mode 100644 index 0000000000..e5fb2546e4 --- /dev/null +++ b/docs/technical_development_guide/source/advanced_tutorial/branching_and_merging.rst @@ -0,0 +1,105 @@ +Branching and Merging +===================== + +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. when to branch from ``latest-os-hpxml``. +Using these guidelines should help to ensure a simple and straightforward merging of new ResStock changes and updates. + +ResStock contains a `git subtree `_ to the `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. +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 `_ +- 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. +Branch from: + +- ``develop`` when updates are not related to the OpenStudio-HPXML subtree, or +- ``latest-os-hpxml`` when updates involve using or testing an OpenStudio-HPXML branch. + +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` for ensuring ResStock is properly connected to OpenStudio-HPXML. + +.. _branch-develop: + +Branch from ``develop`` +----------------------- + +.. _non-os-hpxml-changes: + +Non OpenStudio-HPXML Changes +**************************** + +For updating ResStock's ``develop`` branch for changes related to ... + +.. _syncing-w-latest-os-hpxml: + +Syncing w/Latest OpenStudio-HPXML +********************************* + +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_tasks` 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. + +.. _branch-latest-os-hpxml: + +Branch from ``latest-os-hpxml`` +------------------------------- + +.. _using-latest-os-hpxml: + +Using Latest OpenStudio-HPXML +***************************** + +Ensures you are using the latest in case ``develop`` falls behind ... + +.. _testing-an-os-hpxml-branch: + +Testing an OpenStudio-HPXML Branch +********************************** + +For pulling in and testing a specific OpenStudio-HPXML branch (i.e., that is not the ``master`` branch), first create a test branch in ResStock. +Then enter the following command: + +.. code:: bash + + $ git subtree pull --prefix resources/hpxml-measures https://github.com/NREL/OpenStudio-HPXML.git --squash + +where ```` 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. + +.. _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. diff --git a/docs/technical_development_guide/source/advanced_tutorial/index.rst b/docs/technical_development_guide/source/advanced_tutorial/index.rst index f97a299724..b13100575e 100644 --- a/docs/technical_development_guide/source/advanced_tutorial/index.rst +++ b/docs/technical_development_guide/source/advanced_tutorial/index.rst @@ -17,4 +17,4 @@ If your changes are intended to be merged into the ``develop`` branch of the `Re increasing_upgrade_options upgrade_scenario_config heat_pump_upgrades - openstudio_hpxml \ No newline at end of file + branching_and_merging \ No newline at end of file diff --git a/docs/technical_development_guide/source/advanced_tutorial/openstudio_hpxml.rst b/docs/technical_development_guide/source/advanced_tutorial/openstudio_hpxml.rst deleted file mode 100644 index 05943b115a..0000000000 --- a/docs/technical_development_guide/source/advanced_tutorial/openstudio_hpxml.rst +++ /dev/null @@ -1,53 +0,0 @@ -OpenStudio-HPXML -================ - -ResStock contains a `git subtree `_ to the `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. -As OpenStudio-HPXML is updated, ResStock's ``develop`` branch is periodically updated to point to the latest ``master`` branch of OpenStudio-HPXML, helping to ensure that ResStock stays up-to-date with OpenStudio-HPXML's development. -It may also be helpful to test an OpenStudio-HPXML branch (or tag) using a branch of ResStock. -In both cases, 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 other steps for ensuring ResStock is properly connected to OpenStudio-HPXML. - -.. _latest-os-hpxml: - -Syncing w/latest ----------------- - -For updating ResStock's ``develop`` branch to point to OpenStudio-HPXML's ``master`` branch, branch off of ``develop`` (e.g., with branch name ``latest-os-hpxml``), and then enter the following command: - -.. code:: bash - - $ openstudio tasks.rb update_resources - -See :doc:`running_tasks` 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. - -.. _branch-os-hpxml: - -Testing a branch ----------------- - -For pulling in and testing a specific OpenStudio-HPXML branch (i.e., that is not the ``master`` branch), first create a test branch in ResStock. -Then enter the following command: - -.. code:: bash - - $ git subtree pull --prefix resources/hpxml-measures https://github.com/NREL/OpenStudio-HPXML.git --squash - -where ```` 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. - -.. _other-steps: - -Other 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 -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 From a2f13e2e9025a8c7fcc0f1c111167d80b107c87e Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Fri, 24 Jan 2025 14:42:07 -0700 Subject: [PATCH 10/10] Another refactor of advanced tutorial. --- .../source/advanced_tutorial/index.rst | 13 ++- ...erging.rst => managing_the_repository.rst} | 79 +++++++++---------- ...ng_tasks.rst => running_task_commands.rst} | 4 +- ...lookup.rst => updating_options_lookup.rst} | 10 +-- .../upgrade_scenario_config.rst | 32 +++++--- .../source/basic_tutorial/index.rst | 8 +- ...stallation.rst => installing_resstock.rst} | 13 +-- ...itecture.rst => resstock_architecture.rst} | 8 +- ...{run_project.rst => running_a_project.rst} | 6 +- 9 files changed, 91 insertions(+), 82 deletions(-) rename docs/technical_development_guide/source/advanced_tutorial/{branching_and_merging.rst => managing_the_repository.rst} (75%) rename docs/technical_development_guide/source/advanced_tutorial/{running_tasks.rst => running_task_commands.rst} (98%) rename docs/technical_development_guide/source/advanced_tutorial/{options_lookup.rst => updating_options_lookup.rst} (79%) rename docs/technical_development_guide/source/basic_tutorial/{installation.rst => installing_resstock.rst} (67%) rename docs/technical_development_guide/source/basic_tutorial/{architecture.rst => resstock_architecture.rst} (98%) rename docs/technical_development_guide/source/basic_tutorial/{run_project.rst => running_a_project.rst} (98%) diff --git a/docs/technical_development_guide/source/advanced_tutorial/index.rst b/docs/technical_development_guide/source/advanced_tutorial/index.rst index b13100575e..5480c4e2dd 100644 --- a/docs/technical_development_guide/source/advanced_tutorial/index.rst +++ b/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 `_ 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 `_ repository, a pull request review is required. +This advanced tutorial describes the processes for: .. toctree:: :maxdepth: 2 - running_tasks - options_lookup + managing_the_repository + running_task_commands + updating_options_lookup increasing_upgrade_options upgrade_scenario_config heat_pump_upgrades - branching_and_merging \ No newline at end of file + \ No newline at end of file diff --git a/docs/technical_development_guide/source/advanced_tutorial/branching_and_merging.rst b/docs/technical_development_guide/source/advanced_tutorial/managing_the_repository.rst similarity index 75% rename from docs/technical_development_guide/source/advanced_tutorial/branching_and_merging.rst rename to docs/technical_development_guide/source/advanced_tutorial/managing_the_repository.rst index e5fb2546e4..af6a5d60b4 100644 --- a/docs/technical_development_guide/source/advanced_tutorial/branching_and_merging.rst +++ b/docs/technical_development_guide/source/advanced_tutorial/managing_the_repository.rst @@ -1,12 +1,16 @@ -Branching and Merging -===================== +Managing the Repository +======================= -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. when to branch from ``latest-os-hpxml``. -Using these guidelines should help to ensure a simple and straightforward merging of new ResStock changes and updates. +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 `_ repository. +Note that if your changes are intended to be merged into the ``develop`` branch of the `ResStock `_ repository, a pull request review is required. ResStock contains a `git subtree `_ to the `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` 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. @@ -20,72 +24,61 @@ Other ResStock tasks are developmental in nature and include, e.g.: - 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. -Branch from: - -- ``develop`` when updates are not related to the OpenStudio-HPXML subtree, or -- ``latest-os-hpxml`` when updates involve using or testing an OpenStudio-HPXML branch. - -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` for ensuring ResStock is properly connected to OpenStudio-HPXML. - -.. _branch-develop: - -Branch from ``develop`` ------------------------ +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: -.. _non-os-hpxml-changes: +- 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 -Non OpenStudio-HPXML Changes -**************************** +Using these guidelines should help to ensure a simple and straightforward merging of new ResStock changes and updates. -For updating ResStock's ``develop`` branch for changes related to ... -.. _syncing-w-latest-os-hpxml: +.. _develop_vs_latest_os_hpxml: -Syncing w/Latest OpenStudio-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_tasks` for more information and context about running tasks. +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. -.. _branch-latest-os-hpxml: +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: -Branch from ``latest-os-hpxml`` -------------------------------- +.. code:: bash -.. _using-latest-os-hpxml: + $ git subtree pull --prefix resources/hpxml-measures https://github.com/NREL/OpenStudio-HPXML.git --squash -Using Latest OpenStudio-HPXML -***************************** +where ```` represents the OpenStudio-HPXML branch (or tag) name to be pulled in and tested. -Ensures you are using the latest in case ``develop`` falls behind ... +Note that the previous command essentially mirrors what ``update_resources`` calls, but with a user-specified branch (or tag) name. -.. _testing-an-os-hpxml-branch: +TODO -Testing an OpenStudio-HPXML Branch -********************************** +.. _update_branch: -For pulling in and testing a specific OpenStudio-HPXML branch (i.e., that is not the ``master`` branch), first create a test branch in ResStock. -Then enter the following command: +Update branch +------------- -.. code:: bash +TODO - $ git subtree pull --prefix resources/hpxml-measures https://github.com/NREL/OpenStudio-HPXML.git --squash +.. _merge_branch: -where ```` represents the OpenStudio-HPXML branch (or tag) name to be pulled in and tested. +Merge branch +------------ -Note that the previous command essentially mirrors what ``update_resources`` calls, but with a user-specified branch (or tag) name. +TODO .. _post-git-subtree-steps: -Post ``git subtree`` Steps +Post ``git subtree`` steps -------------------------- After pulling a branch of OpenStudio-HPXML into ResStock, a few additional steps are involved: diff --git a/docs/technical_development_guide/source/advanced_tutorial/running_tasks.rst b/docs/technical_development_guide/source/advanced_tutorial/running_task_commands.rst similarity index 98% rename from docs/technical_development_guide/source/advanced_tutorial/running_tasks.rst rename to docs/technical_development_guide/source/advanced_tutorial/running_task_commands.rst index 9250b2f266..3c1d58b675 100644 --- a/docs/technical_development_guide/source/advanced_tutorial/running_tasks.rst +++ b/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: diff --git a/docs/technical_development_guide/source/advanced_tutorial/options_lookup.rst b/docs/technical_development_guide/source/advanced_tutorial/updating_options_lookup.rst similarity index 79% rename from docs/technical_development_guide/source/advanced_tutorial/options_lookup.rst rename to docs/technical_development_guide/source/advanced_tutorial/updating_options_lookup.rst index 344893ddef..bc9e3a7296 100644 --- a/docs/technical_development_guide/source/advanced_tutorial/options_lookup.rst +++ b/docs/technical_development_guide/source/advanced_tutorial/updating_options_lookup.rst @@ -1,9 +1,9 @@ -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 ` - :ref:`Required argument not provided ` diff --git a/docs/technical_development_guide/source/advanced_tutorial/upgrade_scenario_config.rst b/docs/technical_development_guide/source/advanced_tutorial/upgrade_scenario_config.rst index 51301f88ad..84f7fbd16f 100644 --- a/docs/technical_development_guide/source/advanced_tutorial/upgrade_scenario_config.rst +++ b/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 `. 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 `. +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 `_, 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 `_, 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,7 +30,9 @@ 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 @@ -32,7 +40,9 @@ The apply logic field specifies the conditions under which the option will apply ``!`` 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`. diff --git a/docs/technical_development_guide/source/basic_tutorial/index.rst b/docs/technical_development_guide/source/basic_tutorial/index.rst index 9e12b5bf8d..4846a4c851 100644 --- a/docs/technical_development_guide/source/basic_tutorial/index.rst +++ b/docs/technical_development_guide/source/basic_tutorial/index.rst @@ -3,9 +3,11 @@ Basic Tutorial ============== +This basic tutorial describes: + .. toctree:: :maxdepth: 2 - installation - architecture - run_project + installing_resstock + resstock_architecture + running_a_project diff --git a/docs/technical_development_guide/source/basic_tutorial/installation.rst b/docs/technical_development_guide/source/basic_tutorial/installing_resstock.rst similarity index 67% rename from docs/technical_development_guide/source/basic_tutorial/installation.rst rename to docs/technical_development_guide/source/basic_tutorial/installing_resstock.rst index 41f28019a2..27b9843297 100644 --- a/docs/technical_development_guide/source/basic_tutorial/installation.rst +++ b/docs/technical_development_guide/source/basic_tutorial/installing_resstock.rst @@ -1,5 +1,5 @@ -Installation -============ +Installing ResStock +=================== Download ResStock ----------------- @@ -9,9 +9,11 @@ There are two options for downloading `ResStock `_ on GitHub and select a release. Note the OpenStudio version requirements associated with each version of ResStock. For example, ResStock v2.4.0 requires that you have OpenStudio v2.9.0 installed. +For the first option, go to the `releases page `_ on GitHub and select a release. +Note the OpenStudio version requirements associated with each version of ResStock. For example, ResStock v2.4.0 requires that you have OpenStudio v2.9.0 installed. -For the second option, you will need to have `Git `_ or some other Git-based tool installed. Cloning the ResStock repository gives you access to the ``develop`` branch of ResStock. The ``develop`` branch is under active development. +For the second option, you will need to have `Git `_ or some other Git-based tool installed. +Cloning the ResStock repository gives you access to the ``develop`` branch of ResStock. The ``develop`` branch is under active development. .. note:: @@ -29,4 +31,5 @@ Download the version of OpenStudio software (corresponding to the ResStock versi Developer Instructions ---------------------- -If you will be developing residential measures and testing residential building models, see the :ref:`advanced_tutorial`. If you are a developer, make sure that you have checked out the ``develop`` branch of the repository. +If you will be developing residential measures and testing residential building models, see the :ref:`advanced_tutorial`. +If you are a developer, make sure that you have checked out the ``develop`` or ``latest-os-hpxml`` branch of the repository. diff --git a/docs/technical_development_guide/source/basic_tutorial/architecture.rst b/docs/technical_development_guide/source/basic_tutorial/resstock_architecture.rst similarity index 98% rename from docs/technical_development_guide/source/basic_tutorial/architecture.rst rename to docs/technical_development_guide/source/basic_tutorial/resstock_architecture.rst index 5431cc7ccb..fd9fbd42e1 100644 --- a/docs/technical_development_guide/source/basic_tutorial/architecture.rst +++ b/docs/technical_development_guide/source/basic_tutorial/resstock_architecture.rst @@ -1,7 +1,7 @@ -.. _architecture: +.. _resstock_architecture: -Architecture -============ +ResStock Architecture +===================== The key ResStock workflow components are described below. @@ -17,7 +17,7 @@ The national project contains inputs describing the existing residential buildin The testing project contains inputs to test our OpenStudio workflows. Within each project folder are sample "baseline" and "upgrades" input files that may serve as examples for how to set up different types of ResStock analyses. The contents of the input file ultimately determines the set of workflow steps (i.e., OpenStudio measures) for each ResStock sample. -See :doc:`run_project` for more information about running ResStock analyses. +See :doc:`running_a_project` for more information about running ResStock analyses. Sampling -------- diff --git a/docs/technical_development_guide/source/basic_tutorial/run_project.rst b/docs/technical_development_guide/source/basic_tutorial/running_a_project.rst similarity index 98% rename from docs/technical_development_guide/source/basic_tutorial/run_project.rst rename to docs/technical_development_guide/source/basic_tutorial/running_a_project.rst index 60923d4aa0..664ebe42c3 100644 --- a/docs/technical_development_guide/source/basic_tutorial/run_project.rst +++ b/docs/technical_development_guide/source/basic_tutorial/running_a_project.rst @@ -1,7 +1,7 @@ -.. _run_project: +.. _running_a_project: -Run the Project -=============== +Running a Project +================= Both buildstockbatch and run_analysis.rb can used to run ResStock analyses. They use a common project definition, the YAML file, to provide the details of the analysis.