Merge branch 'develop'

_config.yml

@@ -1,9 +1,10 @@
-remote_theme: pmarsceill/just-the-docs
+# theme: just-the-docs
+remote_theme: just-the-docs/[email protected]
 color_scheme: uo
 title: [URBANopt Docs]
 logo: "/doc_files/URBANopt-Logo-Horizontal-2Color.png"
 description: [Documentation for the URBANopt Software Development Kit]
 heading_anchors: true
 search_enabled: true
 url: https://docs.urbanopt.net
-footer_content: "URBANopt, Copyright (c) 2019-2022, Alliance for Sustainable Energy, LLC, and other contributors. All rights reserved."
+footer_content: "URBANopt, Copyright (c) 2019-2024, Alliance for Sustainable Energy, LLC, and other contributors. All rights reserved."

developer_resources/compatibility_matrix.md

@@ -9,25 +9,30 @@ nav_order: 1
 
 The URBANopt<sup>&trade;</sup> installer includes Ruby and OpenStudio. The matrix below shows the versions details for each installer version.
 
-|URBANopt Version|OpenStudio| OpenStudio-HPXML | Ruby| Python | REopt API | Modelica Buildings Library |
-|:--------------:|:----------:|:--------:|:--------:| :-------: | :-----: | :------------------------: |
-| 0.10.0  			 | 3.6.1      | 1.6.0    |2.7    | 3.10 | v2 | 9 |
-| 0.9.1 - 0.9.2  | 3.5.1      | 1.5.1    |2.7    | 3.10 | v2 | 9 |
-| 0.9.0 				 | 3.5.0 	    | 1.5.0    |2.7    | 3.10 | v2 | 9 |
-| 0.8.0	- 0.8.2	 | 3.4.0		  | 1.4.0		 |2.7		 | 3.7 | v1 | 8 |
-| 0.7.0	- 0.7.1	 | 3.3.0			| 1.3.0		 |2.7		 | 3.7 | v1 | 7 |
-| 0.6.0 - 0.6.4  | 3.2.0      | 1.2.0    |2.7		 |3.7 | v1 | 7 |
-| 0.5.0 - 0.5.1  | 3.1.0      | 1.1.0    |2.5    | 3.7 | v1 |
-| 0.4.0 - 0.4.1  | 3.0.1      |   -      |2.5    | 3.7 | v1 |
-| 0.3.1          | 3.0.1      |		-	     |2.5    | 3.7 | v1 |
+|URBANopt Version|OpenStudio| OpenStudio-HPXML | ResStock | Ruby | Python | REopt API | Modelica Buildings Library |
+|:--------------:|:--------:|:----------------:|:--------:|:----:|:------:|:---------:|:--------------------------:|
+| 0.13.0         | 3.7.0    | 1.7.0            | 3.2.0    | 2.7.2| 3.10   | v2        | 10                         |
+| 0.12.0         | 3.7.0    | 1.7.0            |   -      | 2.7.2| 3.10   | v3        | 10                         |
+| 0.11.0         | 3.7.0    | 1.7.0            |   -      | 2.7.2| 3.10   | v2        | 10                         |
+| 0.10.0  			 | 3.6.1    | 1.6.0            |   -      | 2.7  | 3.10   | v2        | 9                          |
+| 0.9.1 - 0.9.2  | 3.5.1    | 1.5.1            |   -      | 2.7  | 3.10   | v2        | 9                          |
+| 0.9.0 				 | 3.5.0 	  | 1.5.0            |   -      | 2.7  | 3.10   | v2        | 9                          |
+| 0.8.0	- 0.8.2	 | 3.4.0	  | 1.4.0		         |   -      | 2.7	 | 3.7    | v1        | 8                          |
+| 0.7.0	- 0.7.1	 | 3.3.0	  | 1.3.0		         |   -      | 2.7	 | 3.7    | v1        | 7                          |
+| 0.6.0 - 0.6.4  | 3.2.0    | 1.2.0            |   -      | 2.7	 | 3.7    | v1        | 7                          |
+| 0.5.0 - 0.5.1  | 3.1.0    | 1.1.0            |   -      | 2.5  | 3.7    | v1        |   -                        |
+| 0.4.0 - 0.4.1  | 3.0.1    |   -              |   -      | 2.5  | 3.7    | v1        |   -                        |
+| 0.3.1          | 3.0.1    |		-	             |   -      | 2.5  | 3.7    | v1        |   -                        |
 
 
 ## URBANopt Compatibility Matrix
 
 URBANopt<sup>&trade;</sup> depends on various other components to function. Ensure you have the proper version of each dependency for your installed version of URBANopt for expected operation.
 
-|URBANopt Version|URBANopt CLI|OpenStudio|Ruby|Gems   |
-|:--------------:|:----------:|:--------:|:--:|:------------------------------------|
+|URBANopt Version|URBANopt CLI|OpenStudio|Ruby   |Gems                                 |
+|:--------------:|:----------:|:--------:|:-----:|:------------------------------------|
+|**0.12.0**      | 0.12.0     | 3.7      | 2.7.2 | **URBANopt Gems:** <br/>Core Gem v0.11.0 <br/> GeoJSON Gem v0.11.1 <br/> REopt Gem v0.12.0 <br/> Reporting Gem v0.10.0 <br/> RNM-US Gem v0.7.0 <br/> Scenario Gem v0.12.0<br/> **Python Dependencies:** <br/> DISCO v0.5.1 <br/> DiTTo Reader v0.6.4 <br/> GeoJSON Modelica Translator v0.7.0 <br/> ThermalNetwork v0.2.5 **OpenStudio Gems:**<br/>Extension Gem v0.7.1  <br/> Common Measures v0.9.0 <br/> Model Articulation v0.9.0 <br/> Load Flexibility v0.8.0 <br/> EE Gem v0.9.0 <br/> Calibration Gem v0.9.0 <br/> GEB Gem v0.4.0 |
+|**0.11.0**      | 0.11.0     | 3.7      | 2.7.2 | **URBANopt Gems:** <br/>Core Gem v0.11.0 <br/> GeoJSON Gem v0.11.1 <br/> REopt Gem v0.11.0 <br/> Reporting Gem v0.9.1 <br/> RNM-US Gem v0.7.0 <br/> Scenario Gem v0.11.0<br/> **Python Dependencies:** <br/> DISCO v0.4.1 <br/> DiTTo Reader v0.6.3 <br/> GeoJSON Modelica Translator v0.6.0 <br/> ThermalNetwork v0.2.5 **OpenStudio Gems:**<br/>Extension Gem v0.7.1  <br/> Common Measures v0.9.0 <br/> Model Articulation v0.9.0 <br/> Load Flexibility v0.8.0 <br/> EE Gem v0.9.0 <br/> Calibration Gem v0.9.0 <br/> GEB Gem v0.4.0 |
 |**0.10.0**			|0.10.0				|3.6			|2.7.x|**URBANopt Gems:** <br/>Core Gem v0.10.0<br/> GeoJSON Gem v0.10.0 <br/> Scenario Gem v0.10.0<br/> Reporting Gem v0.8.0 <br/> REopt Gem v0.10.0 <br/> RNM-US Gem v0.6.0 <br/> **Python Dependencies:** <br/> DiTTo Reader v0.5.1 <br/> GeoJSON Modelica Translator v0.5.0 <br/> DISCO v0.4.1 <br/> **OpenStudio Gems:**<br/>Extension Gem v0.6.1  <br/> Common Measures v0.8.0 <br/> Model Articulation v0.8.0 <br/> Load Flexibility v0.7.0 <br/> EE Gem v0.8.0 <br/> Calibration Gem v0.8.0 <br/> GEB Gem v0.3.2 |
 |**0.9.0 - 0.9.3**			|0.9.3				|3.5			|2.7.x|**URBANopt Gems:** <br/>Core Gem v0.9.0<br/> GeoJSON Gem v0.9.0 <br/> Scenario Gem v0.9.0<br/> Reporting Gem v0.7.0 <br/> REopt Gem v0.9.0 <br/> RNM-US Gem v0.5.0 <br/> **Python Dependencies:** <br/> DiTTo Reader v0.5.1 <br/> GeoJSON Modelica Translator v0.4.0 <br/> DISCO v0.4.1 <br/> **OpenStudio Gems:**<br/>Extension Gem v0.6.0  <br/> Common Measures v0.7.0 <br/> Model Articulation v0.7.0 <br/> Load Flexibility v0.6.1 <br/> EE Gem v0.7.0 <br/> Calibration Gem v0.7.0 <br/> GEB Gem v0.2.1 |
 |**0.8.3**			|0.8.3				|3.4			|2.7.x|**URBANopt Gems:** <br/>Core Gem v0.8.0<br/> GeoJSON Gem v0.8.1 <br/> Scenario Gem v0.8.0<br/> Reporting Gem v0.6.1 <br/> REopt Gem v0.8.0 <br/> RNM-US Gem v0.4.0 <br/> DiTTo Reader v0.4.0 <br/> GeoJSON Modelica Translator v0.2.3 <br/> **OpenStudio Gems:**<br/>Extension Gem v0.5.1  <br/> Common Measures v0.6.1 <br/> Model Articulation v0.6.1 <br/> Load Flexibility v0.5.0 <br/> EE Gem v0.6.0 <br/> Calibration Gem v0.6.0 |

developer_resources/developer_resources.md

@@ -21,30 +21,30 @@ has_toc: false
 	1. Use the “DO NOT MERGE” label for Pull Requests that should not be merged
 
 ## Functionality Development / Copying over to the CLI
-Functionality should be developed in the urbanopt-example-geojson-project repo. once it is ready and passing tests, the files from urbanopt-example-geojson-project will be copied over to the urbanopt-cli repo. Take care when performing the copy process as it is possible some changes were made directly on the cli repo (i.e., you might have to diff the files and reconcile both repos with the latest changes).
+Functionality should be developed in the urbanopt-example-geojson-project repo. Once it is ready and passing tests, the files from urbanopt-example-geojson-project will be copied over to the urbanopt-cli repo. Take care when performing the copy process as it is possible some changes were made directly on the cli repo (i.e., you might have to diff the files and reconcile both repos with the latest changes).
 
 Notes for the copy process (from example-project repo to cli repo):
 1. Copy example_project/resources folder to example_files/resources
-2. Copy mappers folder over. **Note:** take the residential folder that is within the mappers folder and put it next to the mappers folder in the CLI repo
-3. Copy base_workflow.osw again and place it next to the mappers folder. Rename it as base_workflow_res.osw and place it NEXT TO the mappers folder (not inside).
-4. Open mappers/base_workflow.osw file in cli repo (you have previously copied it over in step 2) Remove the "BuildResidentialModel" measure section completely from this file and save.
-5. copy the measures folder to example_files/measures
-6. copy xml_building to example_files/xml_building
-7. copy osm_building to example_files/osm_building
-8. copy reopt to example_files/reopt. (on this one maybe diff the files to ensure that changes weren't just made on the CLI repo)
-9. copy visualization to example_files/visualization
-10. There is no need to copy any of the scenario CSVs
+1. Copy mappers folder over. **Note:** take the residential folder that is within the mappers folder and put it next to the mappers folder in the CLI repo
+1. Copy base_workflow.osw again and place it next to the mappers folder. Rename it as base_workflow_res.osw and place it NEXT TO the mappers folder (not inside).
+1. Open mappers/base_workflow.osw file in cli repo (you have previously copied it over in step 2) Remove the "BuildResidentialModel" measure section completely from this file and save.
+1. copy the measures folder to example_files/measures
+1. copy xml_building to example_files/xml_building
+1. copy osm_building to example_files/osm_building
+1. copy reopt to example_files/reopt. (on this one maybe diff the files to ensure that changes weren't just made on the CLI repo)
+1. copy visualization to example_files/visualization
+1. There is no need to copy any of the scenario CSVs
 
 
 ## Conflicting packages
 
-If you make changes, ensure that all gems use the  `openstudio-standard` gem shipped with OpenStudio to avoid unforeseen consequences (**do not** include an _openstudio-standard_ dependency in the gemfile).
+If you make changes, ensure that all gems use the `openstudio-standards` gem shipped with OpenStudio to avoid unforeseen consequences (**do not** include an _openstudio-standards_ dependency in the gemfile).
 
 
 ## Generating rdoc Documentation
-Follow these steps to generate rdocs for now and existing SDK gems:
+Follow these steps to generate rdocs for new and existing SDK gems:
 1. Install [NodeJS](https://nodejs.org/en/)
-1. Go to the repository docs file, eg. _urbanopt-scenario-gem/docs_ and type `npm install`. Note: access to developerVPN will be needed for this step if within the NREL firewall.
+1. Go to the repository docs file, eg. _urbanopt-scenario-gem/docs_ and type `npm install`
 1. Move to the root level of the repo, eg. _urbanopt-scenario-gem_ and enter these commands:
 	```
     bundle exec rdoc --template-stylesheets ./docs/.vuepress/public/custom_rdoc_styles.css
@@ -56,9 +56,9 @@ Rdoc options are controlled with this [config file](https://github.com/urbanopt/
 
 ## Developing with the CLI
 
-When developing locally on URBANopt<sup>&trade;</sup> core gems and testing new functionality and dependencies via the CLI, it may be necessary to install local versions of core gems.
+When developing locally on URBANopt<sup>&trade;</sup> gems and testing new functionality and dependencies via the CLI, it may be necessary to install local versions of some gems.
 
-For local development, you will want to set the environment variable *FAVOR_LOCAL_GEMS* to 1. This enables local copies of gems in the Gemfile.  Note that setting *FAVOR_LOCAL_GEMS* to 0 will not undo local gems functionality: you will have to either remove the *FAVOR_LOCAL_GEMS* environment variable, set it to *nil* or *false* (not 0), and open a new terminal window to turn it off.
+For local development, you will want to set the environment variable *FAVOR_LOCAL_GEMS* to 1. This enables local copies of gems in the Gemfile.  Note that setting *FAVOR_LOCAL_GEMS* to 0 will not undo local gems functionality: you will have to either remove the *FAVOR_LOCAL_GEMS* environment variable or set it to *nil* or *false* (not 0), and open a new terminal window to turn it off.
 
 There are 2 Gemfiles of interest:
 

developer_resources/known_issues.md

@@ -26,7 +26,7 @@ nav_order: 3
 	bundle exec certified-update
 	```
 
-	If you are using an URBANopt installer, locate the path within the installed application of the 'certified-update' executable and run it.  For example, on MAC the path would be something like:
+	If you are using an URBANopt installer, locate the path within the installed application of the 'certified-update' executable and run it.  For example, on Mac the path would be something like:
 	```bash
 	/Applications/URBANoptCLI_X.X.X/gems/ruby/2.7.0/gems/certified-1.0.0/bin/certified-update
 	```
@@ -46,22 +46,29 @@ nav_order: 3
 
 1. **Residential HPXML workflow and Non-US Weather Files** This workflow supports only US weather files at this time. If you have a weather file outside of the US, a possible work-around is to add a row to the climate zone lookup file with your weather file's WMO and climate_zone. The file can be found in your project directory under:
 
-	```bash 
+	```bash
 	resources/hpxml-resources/HPXMLtoOpenStudio/resources/data/climate_zones.csv
 	```
 
 ### Version 0.7.0 through 0.9.0
 1. Residential stochastic schedules are silently failing in UO v0.7.0-v0.9.0 and the default schedules are instead being used. Use version v0.10.0 and above to resolve this issue.
 
+### Version 0.9.2 and below
+1. An unpinned ruby dependency in the `parser` gem is causing an issue with runnig URBANopt projects. You may get an error related to URBANopt being unable to find the dependency `racc`.
+To fix the issue, either download URBANopt CLI 0.9.3 and recreate/update your projects. Or, since this issue is isolated to the files in your project directory, you can also add the following line to the Gemfile *inside your project directory* and re-run your simulation:
+```
+	gem 'parser 3.2.2.2'
+```
+
 ### Version 0.9.1 and below
 1. An unpinned ruby dependency has been updated and is causing an issue with running URBANopt projects.  If you get an error related to `unicode_normalize` similar to this:
 	```bash
 	lib/openstudio/workflow/util/measure.rb failed with message cannot load such file -- unicode_normalize/normalize.rb
 	      ...
 	```
 
-To fix this issue, either download URBANopt CLI 0.9.2 and recreate/update your projects.
-Since this issue is isolated to the files in your project directory, you can also add the following line to the Gemfile *inside your project directory* and re-run your simulation:
+    To fix this issue, either download URBANopt CLI 0.9.2 and recreate/update your projects.
+    Since this issue is isolated to the files in your project directory, you can also add the following line to the Gemfile *inside your project directory* and re-run your simulation:
 	```
 		gem 'addressable', '2.8.1'
 	```
@@ -81,7 +88,7 @@ Since this issue is isolated to the files in your project directory, you can als
 	gem install urbanopt-cli
 	```
 
-1. This version contains a known bug related to the feature CSV reports and the scenario-level SQL database.  It is recommended that you upgrade to version 0.4.1.
+1. This version contains a known bug related to the feature CSV reports and the scenario-level SQL database. Please use version 0.4.1 instead.
 
 1. URBANopt<sup>&trade;</sup> SDK version 0.4.0 includes OpenDSS support via the URBANopt CLI.  Windows users may experience errors detecting python and urbanopt-ditto-reader when using the `opendss` CLI command.  If you are not able to run OpenDSS through the CLI, the functionality is also available manually by following the general [OpenDSS instructions](../opendss/opendss.md#converting-and-running-opendss).
 

developer_resources/release_instructions.md

@@ -28,20 +28,14 @@ We recommend releasing gems **in order from the base to most dependent**. For ea
 	```
 1. Remove .DS_Store files if any are in the repo
 1. If the gem has rdoc documentation, [regenerate the rdocs](../developer_resources/developer_resources.md#generating-rdoc-documentation)
-1. Run the changelog rake task and add the changes to the CHANGELOG file for the range of time between last release and this release. Also make sure that all pull requests have a related Issue to be included in the change log.
-	```
-	rake openstudio:change_log[start_date,end_date,apikey]
-	```
-    No spaces around the commas! Paste the `Closed Issues` into the CHANGELOG, matching formatting as appropriate.
 1. Ensure that the Gemfile and gemspec files are "clean" and that no dependency is pointing to a github branch before merging to develop and main branches.
 1. Merge pull requests to the `develop` branch
+1. On GitHub, go to the releases page and draft a latest release tag. Name it “Version x.y.z”. Use the Github automated changelog generation and copy the CHANGELOG entry into the changelog file.
+1. Update the documentation with detailed usage and helpful examples
+1. Update [Compatibility Matrix](compatibility_matrix.md) as appropriate
 1. Create PR to main
     - Ensure all tests pass before merging
 1. Locally - from the main branch, run `rake release` to release the gem to RubyGems
-1. Update the documentation with detailed usage and helpful examples
-1. On GitHub, go to the releases page and update the latest release tag. Name it “Version x.y.z” and copy the CHANGELOG entry into the text box.
-    - Link to relevant documentation URLs in release tags
-1. Update [Compatibility Matrix](compatibility_matrix.md) as appropriate
 
 ### Updates for New Version of OpenStudio
 Follow these steps when testing URBANopt for a new version of OpenStudio. These changes should be made on all URBANopt Ruby gems, the example-geojson-project repo, and the CLI: