diff --git a/_config.yml b/_config.yml index dd23c0e4..8956cdb5 100644 --- a/_config.yml +++ b/_config.yml @@ -1,4 +1,5 @@ -remote_theme: pmarsceill/just-the-docs +# theme: just-the-docs +remote_theme: just-the-docs/just-the-docs@v0.5.2 color_scheme: uo title: [URBANopt Docs] logo: "/doc_files/URBANopt-Logo-Horizontal-2Color.png" @@ -6,4 +7,4 @@ 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." diff --git a/_site/index.html b/_site/index.html index 5d1e5e7d..5edd58a6 100644 --- a/_site/index.html +++ b/_site/index.html @@ -1 +1 @@ - Home - URBANopt Docs Home | [“URBANopt Docs”] Link Search Menu Expand Document

urbanopt logo

URBANopt SDK Documentation

URBANopt™ (Urban Renewable Building And Neighborhood optimization) is an EnergyPlus™- and OpenStudio©-based simulation platform aimed at district- and campus-scale thermal and electrical analysis for Community and Urban District Energy Modeling.

URBANopt is not a standalone program for end users. URBANopt is a Software Development Kit (SDK) — a collection of open source modules focused on underlying analytics for a variety of multi-building design and analysis use cases. Commercial software developers can use existing URBANopt modules, customize URBANopt modules, and create new modules to help implement the desired workflows for their end user tools. Other users of the SDK could include researchers looking to create customized workflows to perform specific environmental design tasks.

graphic showing urbanopt at a high level

Use Cases

The URBANopt project is focused on enabling three primary use cases:

  1. Design of low energy campuses and districts through multi-building efficiency scenario analysis
  2. Design and optimization of grid-interactive efficient buildings (GEBs) at a district-scale in conjunction with distributed energy resources (DERs) and electric distribution systems
  3. Detailed design of next-generation district thermal systems

A summary of the capabilities associated with each use case is shown below:

main urbanopt capabilities

click to expand image

A diagram of the technologies needed to enable each capability is shown below:

uo ecosystem diagram

Getting Started — Visit the Getting Started page for detailed instructions on how to use URBANopt in a variety of workflows. You can also view the tutorial videos to guide you through various aspects of the URBANopt SDK and its workflows.

Workflows — For more details about the workflows enabled through URBANopt, visit the Workflows section.

Resources — Visit the Resources section for general information on URBANopt structure and customizations.

For Developers — Visit the Developer Resources section for details on how to develop and test new URBANopt functionality as well as a compatibility matrix for all URBANopt dependencies.

Questions, Comments, Requests? — Visit the new URBANopt Discussions page on GitHub to ask questions or make feature requests.

URBANopt, Copyright (c) 2019-2022, Alliance for Sustainable Energy, LLC, and other contributors. All rights reserved.

+ Home - URBANopt Docs Home | [“URBANopt Docs”] Link Search Menu Expand Document

urbanopt logo

URBANopt SDK Documentation

URBANopt™ (Urban Renewable Building And Neighborhood optimization) is an EnergyPlus™- and OpenStudio©-based simulation platform aimed at district- and campus-scale thermal and electrical analysis for Community and Urban District Energy Modeling.

URBANopt is not a standalone program for end users. URBANopt is a Software Development Kit (SDK) — a collection of open source modules focused on underlying analytics for a variety of multi-building design and analysis use cases. Commercial software developers can use existing URBANopt modules, customize URBANopt modules, and create new modules to help implement the desired workflows for their end user tools. Other users of the SDK could include researchers looking to create customized workflows to perform specific environmental design tasks.

graphic showing urbanopt at a high level

Use Cases

The URBANopt project is focused on enabling three primary use cases:

  1. Design of low energy campuses and districts through multi-building efficiency scenario analysis
  2. Design and optimization of grid-interactive efficient buildings (GEBs) at a district-scale in conjunction with distributed energy resources (DERs) and electric distribution systems
  3. Detailed design of next-generation district thermal systems

A summary of the capabilities associated with each use case is shown below:

main urbanopt capabilities

click to expand image

A diagram of the technologies needed to enable each capability is shown below:

uo ecosystem diagram

Getting Started — Visit the Getting Started page for detailed instructions on how to use URBANopt in a variety of workflows. You can also view the tutorial videos to guide you through various aspects of the URBANopt SDK and its workflows.

Workflows — For more details about the workflows enabled through URBANopt, visit the Workflows section.

Resources — Visit the Resources section for general information on URBANopt structure and customizations.

For Developers — Visit the Developer Resources section for details on how to develop and test new URBANopt functionality as well as a compatibility matrix for all URBANopt dependencies.

Questions, Comments, Requests? — Visit the new URBANopt Discussions page on GitHub to ask questions or make feature requests.

URBANopt, Copyright (c) 2019-2024, Alliance for Sustainable Energy, LLC, and other contributors. All rights reserved.

diff --git a/developer_resources/compatibility_matrix.md b/developer_resources/compatibility_matrix.md index 5582def2..5cbe7944 100644 --- a/developer_resources/compatibility_matrix.md +++ b/developer_resources/compatibility_matrix.md @@ -9,25 +9,30 @@ nav_order: 1 The URBANopt™ 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™ 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:**
Core Gem v0.11.0
GeoJSON Gem v0.11.1
REopt Gem v0.12.0
Reporting Gem v0.10.0
RNM-US Gem v0.7.0
Scenario Gem v0.12.0
**Python Dependencies:**
DISCO v0.5.1
DiTTo Reader v0.6.4
GeoJSON Modelica Translator v0.7.0
ThermalNetwork v0.2.5 **OpenStudio Gems:**
Extension Gem v0.7.1
Common Measures v0.9.0
Model Articulation v0.9.0
Load Flexibility v0.8.0
EE Gem v0.9.0
Calibration Gem v0.9.0
GEB Gem v0.4.0 | +|**0.11.0** | 0.11.0 | 3.7 | 2.7.2 | **URBANopt Gems:**
Core Gem v0.11.0
GeoJSON Gem v0.11.1
REopt Gem v0.11.0
Reporting Gem v0.9.1
RNM-US Gem v0.7.0
Scenario Gem v0.11.0
**Python Dependencies:**
DISCO v0.4.1
DiTTo Reader v0.6.3
GeoJSON Modelica Translator v0.6.0
ThermalNetwork v0.2.5 **OpenStudio Gems:**
Extension Gem v0.7.1
Common Measures v0.9.0
Model Articulation v0.9.0
Load Flexibility v0.8.0
EE Gem v0.9.0
Calibration Gem v0.9.0
GEB Gem v0.4.0 | |**0.10.0** |0.10.0 |3.6 |2.7.x|**URBANopt Gems:**
Core Gem v0.10.0
GeoJSON Gem v0.10.0
Scenario Gem v0.10.0
Reporting Gem v0.8.0
REopt Gem v0.10.0
RNM-US Gem v0.6.0
**Python Dependencies:**
DiTTo Reader v0.5.1
GeoJSON Modelica Translator v0.5.0
DISCO v0.4.1
**OpenStudio Gems:**
Extension Gem v0.6.1
Common Measures v0.8.0
Model Articulation v0.8.0
Load Flexibility v0.7.0
EE Gem v0.8.0
Calibration Gem v0.8.0
GEB Gem v0.3.2 | |**0.9.0 - 0.9.3** |0.9.3 |3.5 |2.7.x|**URBANopt Gems:**
Core Gem v0.9.0
GeoJSON Gem v0.9.0
Scenario Gem v0.9.0
Reporting Gem v0.7.0
REopt Gem v0.9.0
RNM-US Gem v0.5.0
**Python Dependencies:**
DiTTo Reader v0.5.1
GeoJSON Modelica Translator v0.4.0
DISCO v0.4.1
**OpenStudio Gems:**
Extension Gem v0.6.0
Common Measures v0.7.0
Model Articulation v0.7.0
Load Flexibility v0.6.1
EE Gem v0.7.0
Calibration Gem v0.7.0
GEB Gem v0.2.1 | |**0.8.3** |0.8.3 |3.4 |2.7.x|**URBANopt Gems:**
Core Gem v0.8.0
GeoJSON Gem v0.8.1
Scenario Gem v0.8.0
Reporting Gem v0.6.1
REopt Gem v0.8.0
RNM-US Gem v0.4.0
DiTTo Reader v0.4.0
GeoJSON Modelica Translator v0.2.3
**OpenStudio Gems:**
Extension Gem v0.5.1
Common Measures v0.6.1
Model Articulation v0.6.1
Load Flexibility v0.5.0
EE Gem v0.6.0
Calibration Gem v0.6.0 | diff --git a/developer_resources/developer_resources.md b/developer_resources/developer_resources.md index cf8bc09a..6342030d 100644 --- a/developer_resources/developer_resources.md +++ b/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™ 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™ 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: diff --git a/developer_resources/known_issues.md b/developer_resources/known_issues.md index 13dfdf50..b3179cbb 100644 --- a/developer_resources/known_issues.md +++ b/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,13 +46,20 @@ 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 @@ -60,8 +67,8 @@ nav_order: 3 ... ``` -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™ 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). diff --git a/developer_resources/release_instructions.md b/developer_resources/release_instructions.md index bca199f0..0443a287 100644 --- a/developer_resources/release_instructions.md +++ b/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: diff --git a/doc_files/ghp2.PNG b/doc_files/ghp2.PNG new file mode 100644 index 00000000..b8c81cd3 Binary files /dev/null and b/doc_files/ghp2.PNG differ diff --git a/doc_files/os-hpxml-resstock-workflow.png b/doc_files/os-hpxml-resstock-workflow.png new file mode 100644 index 00000000..870ca4dc Binary files /dev/null and b/doc_files/os-hpxml-resstock-workflow.png differ diff --git a/installation/des_installation.md b/installation/des_installation.md index 4250c7a9..195fd6db 100644 --- a/installation/des_installation.md +++ b/installation/des_installation.md @@ -9,7 +9,7 @@ nav_order: 5 ## Installation via URBANopt CLI -1. Run the following URBANopt CLI command to install all URBANopt python dependencies. As of version 0.9.0, URBANopt requires Python v3.10. +1. Run the following URBANopt CLI command to install all URBANopt python dependencies, which includes the GeoJSON-to-Modelica-Translator (GMT). As of version 0.9.0, URBANopt requires Python v3.10. ```bash uo install_python ``` @@ -80,12 +80,12 @@ GeoJSON and System Parameter file from results of an URBANopt SDK simulation res This Installation guide is broken up into three major setup steps: 1. [Installing the GMT](#gmt-installation) -2. [Installing and configuring the Modelica Buildings Library (MBL)](#mbl-installation) -3. [Installing and configuring Docker in order to run simulations using JModelica](#docker-installation) +1. [Installing and configuring the Modelica Buildings Library (MBL)](#mbl-installation) +1. [Installing and configuring Docker in order to run simulations using JModelica](#docker-installation) ### GMT Installation -You must have PIP and Python 3.7 or later installed (run `python --version` to see what version you're using). After installing Python and PIP run the following in a terminal (requires Python 3): +You must have PIP and Python 3.8 or later installed (run `python --version` to see what version you're using). After installing Python and PIP run the following in a terminal, ideally in a virtual environment (requires Python 3): ```bash pip install geojson-modelica-translator @@ -109,7 +109,7 @@ The Modelica Buildings Library contains many models that are needed to assemble Installation of the MBL is done through Git and GitHub. Follow the instructions below to install the MBL needed for the GMT: - Download and extract [the MBL](https://simulationresearch.lbl.gov/modelica/downloads/archive/modelica-buildings.html) - - See the [compatibility matrix](../developer_resources/compatibility_matrix.md) for appropriate version + - See the [compatibility matrix](../developer_resources/compatibility_matrix.md) for appropriate MBL version - Add the Modelica Buildings Library path to your MODELICAPATH environment variable (e.g., `export MODELICAPATH=${MODELICAPATH}:$HOME/path/to/modelica-buildings`). Restart your terminal to ensure that the MBL library is exported correctly. Once the MBL is installed, the CLI can be used to create the model with the following command: @@ -124,16 +124,13 @@ Once the MBL is installed, the CLI can be used to create the model with the foll The resulting Modelica package will be created and can be opened in a Modelica editor. Open the `package.mo` file in the root directory of the generated package. You will also need to load the MBL into your Modelica editor. -#### Docker Installation +### Docker Installation -In GMT version >=0.3.0, the only method of running the simulations for models built by the GMT is within Dymola. Alternative approaches are currently in development. The following instructions apply to GMT <= 0.3.0. - -The GMT versions prior to 0.3.0 enabled running of the models using JModelica. It requires the -installation of [Docker](https://docs.docker.com/get-docker/). To configure Docker, do the following: +In GMT version >=0.5.0, district models can be simulated by using OpenModelica, which is included with the GMT. This does require the installation of [Docker](https://docs.docker.com/get-docker/). To configure Docker, do the following: - Install [Docker](https://docs.docker.com/get-docker/) for your system. - Configure Docker Desktop to have at least 4 GB Ram and 2 cores. This is configured under the Docker Preferences. -- It is recommended to test the installation of Docker by simply running `docker run hello-world` in a terminal. +- We recommend testing the installation of Docker by running `docker run hello-world` in a terminal. After Docker is installed and configured, you can use the CLI to run the model using the following command: diff --git a/installation/disco.md b/installation/disco.md index 11de197f..e56d81e2 100644 --- a/installation/disco.md +++ b/installation/disco.md @@ -27,11 +27,12 @@ uo install_python This installs to the following versions of the python packages: -|Python Package|Version| -|:--------------:|:----------:| -| NREL-disco| 0.4.0 | -| urbanopt-ditto-reader| 0.4.1 | -| geojson-modelica-translator|0.3.0 | +|Python Package |Version | +|:---------------------------:|:------:| +| NREL-disco | 0.4.0 | +| urbanopt-ditto-reader | 0.6.3 | +| geojson-modelica-translator | 0.6.0 | +| ThermalNetwork | 0.2.3 | To update these versions, modify the version in the *dependencies.json* diff --git a/installation/linux.md b/installation/linux.md index 0e113a89..d71729e3 100644 --- a/installation/linux.md +++ b/installation/linux.md @@ -45,7 +45,7 @@ e.g.: ```/usr/local/urbanopt-cli-0.3.1/``` gem install bundler -v 2.1 ``` -1. Install [OpenStudio 3.4.0](https://github.com/NREL/OpenStudio/releases/tag/v3.4.0) +1. Install [OpenStudio 3.7.0](https://github.com/NREL/OpenStudio/releases/tag/v3.7.0) OpenStudio is designed to be used on Ubuntu 18.04. For other Ubuntu versions, see the [troubleshooting](troubleshooting.md) page. @@ -86,6 +86,6 @@ The python installation path will be printed in the terminal once python is succ ## DES Installation -As of version 0.5.2, the URBANopt CLI includes DES support. This functionality is implemented in Python and Modelica requires that various dependencies be installed before use. +As of version 0.5.2, the URBANopt CLI includes DES support. This functionality is implemented in Python and Modelica and requires that additional dependencies be installed before use. While the GeoJSON Modelica Translator will be installed automatically with the UO CLI `install_python` command, follow the [DES Installation Instructions](./des_installation.md) to install additional dependencies related to this workflow. diff --git a/installation/mac.md b/installation/mac.md index b8deff95..a609f59b 100644 --- a/installation/mac.md +++ b/installation/mac.md @@ -47,7 +47,7 @@ Follow the steps below or watch the [Mac Manual Installation Video](https://urba gem install bundler -v 2.1 ``` -1. Install [OpenStudio 3.4.0](https://github.com/NREL/OpenStudio/releases/tag/v3.4.0) +1. Install [OpenStudio 3.7.0](https://github.com/NREL/OpenStudio/releases/tag/v3.7.0) 1. Add the `RUBYLIB` path as an "environment variable", pointing to the OpenStudio Ruby location you just installed. You can use a text editor such as TextEdit, Sublime Text, vi or nano to open `.bash_profile` (or `.zshenv` if using zsh, the default since MacOS 10.15 Catalina). The following is an example using nano: @@ -84,6 +84,6 @@ The python installation path will be printed in the terminal once python is succ ## DES Installation -As of version 0.5.2, the URBANopt CLI includes DES support. This functionality is implemented in Python and Modelica requires that various dependencies be installed before use. +As of version 0.5.2, the URBANopt CLI includes DES support. This functionality is implemented in Python and Modelica and requires that additional dependencies be installed before use. While the GeoJSON Modelica Translator will be installed automatically with the UO CLI `install_python` command, follow the [DES Installation Instructions](./des_installation.md) to install additional dependencies related to this workflow. diff --git a/installation/windows.md b/installation/windows.md index 210c9881..4beca984 100644 --- a/installation/windows.md +++ b/installation/windows.md @@ -22,7 +22,9 @@ Follow the steps below or watch the [Windows Installer Video](https://urbanopt-t 1. Use the GUI installer and choose a directory to install. Once installed, open a terminal and run the provided setup script for that shell (below are the setup scripts for each respective shell environment). -**Note: GitBash is recommended** If you are unfamiliar with git or GitBash, you can check out this [video tutorial](https://www.youtube.com/watch?v=iGutIN5t9Mo). +**Note: GitBash is recommended** + +If you are unfamiliar with git or GitBash, you can check out this [video tutorial](https://www.youtube.com/watch?v=iGutIN5t9Mo). **GitBash** ```terminal @@ -44,7 +46,7 @@ c:\urbanopt-cli-X.X.X\setup-env.bat -Important Note Each time you want to work on URBAnopt and you open a new terminal to do so, you will need to run the `env_uo` script to configure your terminal session environment: +Important Note Each time you want to work on URBANopt and you open a new terminal to do so, you will need to run the `env_uo` script to configure your terminal session environment: **GitBash** ```terminal @@ -84,7 +86,7 @@ Follow the steps below or watch the [Windows Manual Installation Video](https:// gem install bundler -v 2.1 ``` -1. Install [OpenStudio 3.4.0](https://github.com/NREL/OpenStudio/releases/tag/v3.4.0) +1. Install [OpenStudio 3.7.0](https://github.com/NREL/OpenStudio/releases/tag/v3.7.0) 1. Create file `C:\ruby-2.7.2-1-x64-mingw32\lib\ruby\site_ruby\openstudio.rb` and edit it to contain the path to your installed OpenStudio (where X.X.X is the OpenStudio version installed): @@ -135,6 +137,6 @@ The python installation path will be printed in the terminal once python is succ ## DES Installation -As of version 0.5.2, the URBANopt CLI includes DES support. This functionality is implemented in Python and Modelica requires that various dependencies be installed before use. +As of version 0.5.2, the URBANopt CLI includes DES support. This functionality is implemented in Python and Modelica and requires that additional dependencies be installed before use. While the GeoJSON Modelica Translator will be installed automatically with the UO CLI `install_python` command, follow the [DES Installation Instructions](./des_installation.md) to install additional dependencies related to this workflow. diff --git a/resources/publications.md b/resources/publications.md index d637dbb9..ed3b42f3 100644 --- a/resources/publications.md +++ b/resources/publications.md @@ -7,14 +7,37 @@ nav_order: 6 ## Publications and Presentations +### 2024 + +- Robert Flores, Sammy Houssainy, Weixi Wang, Khanh Nguyen Cu, Xiao Nie, Noah Woolfolk, Ben Polly, Ramin Faramarzi, Jim Maclay, Jaeho Lee, Jack Brouwer (2024) [Addressing building related energy burden, air pollution, and carbon emissions of a low-income community in Southern California](https://doi.org/10.1016/j.adapen.2024.100169) Advances in Applied Energy Volume 14, 100169, ISSN 2666-7924 + +### 2023 + +- Jing Wang, Rawad El Kontar, Xin Jin, Jennifer King (2023) [Decarbonizing all-electric communities via carbon-responsive control of behind-the-meter resources](https://doi.org/10.1016/j.adapen.2023.100139) Advances in Applied Energy, Volume 10, 100139, ISSN 2666-7924 + +- Kaiyu Sun, Wanni Zhang, David Goldwasser, Tanushree Charan, Katherine Fleming, Lauren Klun, Ben Polly, Tianzhen Hong (2023) [Development of Prototypical District-Scale Models](https://www.nrel.gov/docs/fy23osti/86589.pdf) NREL + +- Robert Flores, Sammy Houssainy, Weixi Wang, Joseph Robertson, Khanh Nguyen Cu, Ben Polly, Ramin Faramarzi, Jim Maclay, Jack Brouwer (2023) [Developing and tuning a community scale energy model for a disadvantaged community](https://doi.org/10.1016/j.enbuild.2023.112861) Energy and Buildings, Volume 285, 112861, ISSN 0378-7788 + ### 2022 +- Peter Schneider,Leslie Badger, Dusan Brhlik, David Goldwasser, Ben Polly (2022) [Resilient, Rural, and Revolutionary: Salisbury Square's Direct-Current Affordable Microgrid Community](https://www.nrel.gov/docs/fy22osti/83181.pdf) NREL + +- Rawad El Kontar, Jing Wang, Xin Jin, Jennifer King, Tarek Rakha (2022) [Probabilistic Modeling of Commercial Building Occupancy Patterns Using Location-Based Map Data](https://www.nrel.gov/docs/fy22osti/83345.pdf) NREL + +- Jing Wang, Rawad El Kontar, Xin Jin, Jennifer King (2022) [Electrifying High-Efficiency Future Communities: Impact on Energy, Emissions, and Grid](https://doi.org/10.1016/j.adapen.2022.100095) Advances in Applied Energy, Volume 6, 100095, ISSN 2666-7924 + +- Allen, A., Henze, G., Baker, K., Pavlak, G, and Murphy, M. (2022). [An optimization framework for the network design of advanced district thermal energy systems](https://doi.org/10.1016/j.enconman.2022.115839), Energy Conversion and Management, 266, 115839. + - Lämmle, M., Allen, A., Henze, G., Pless, S. (2022). [Valuation of Novel Waste Heat Sources and a Path Towards Adoption](https://www.nrel.gov/docs/fy22osti/83352.pdf). ACEEE Summer Study on Energy Efficiency in Buildings. - Zahra Fallahi, P., Houssainy, S., Ling, J., Leach, M., Klun, L., Slovensky, M. (2022). [Designing for Zero Energy and Zero Carbon on a Multi-Building Scale using URBANopt](https://www.nrel.gov/docs/fy22osti/83457.pdf). ACEEE Summer Study on Energy Efficiency in Buildings. ### 2021 + +Meyer, Ryan, Bridgeland, Brett, Woldekidan, Korbaga, Webster, Brett, Charan, Tanushree, Lewe, Jung-Ho, Olgyay, Victor, & Zaleski, Sarah. (2021) [GT Flex: A Coordinated Multi-Building Pilot Study](https://doi.org/10.2172/1823767). + Charan, T., Mackey, C., Irani, A., Polly, B., Ray, S., Fleming, K., El Kontar, R., Moore, N., Elgindy, T., Cutler, D., Roudsari, M. S., & Goldwasser, D. (2021). [Integration of Open-Source URBANopt and Dragonfly Energy Modeling Capabilities into Practitioner Workflows for District-Scale Planning and Design](https://doi.org/10.3390/en14185931). De Rosa, L., Domingo, C. M., Gómez, T., Roman, S., Kontar, R. El, Polly, B., Fleming, K., & Elgindy, T. (2021). [Integrated models for electrical distribution network planning and district-scale building energy use](https://doi.org/10.1109/PowerTech46648.2021.9494767). IEEE Madrid PowerTech. @@ -27,7 +50,7 @@ Long, Nicholas, Antoine Gautier, Hagar Elarga, Amy Allen, Ted Summer, Lauren Klu ### 2020 -Rawad El Kontar, Ben Polly, Tanushree Charan, Katherine Fleming, Nathan Moore, Nicholas Long, & David Goldwasser. (2020). (PDF) URBANopt: [An Open-Source Software Development Kit for Community and Urban District Energy Modeling](https://www.nrel.gov/docs/fy21osti/76781.pdf). ASHRAE/IBPSA-USA Building Performance Modeling Conference And SimBuild. +Rawad El Kontar, Ben Polly, Tanushree Charan, Katherine Fleming, Nathan Moore, Nicholas Long, & David Goldwasser. (2020) [URBANopt: An Open-Source Software Development Kit for Community and Urban District Energy Modeling](https://www.nrel.gov/docs/fy21osti/76781.pdf). ASHRAE/IBPSA-USA Building Performance Modeling Conference And SimBuild. Houssainy, Sammy, Faramarzi, Ramin, Farahmand, Farhad, Pande, Abhjieet, and Griesser, Jon. (2020). [Community-Scale Energy Efficiency Assessment for Zero Net Energy Using the URBANopt Simulation Platform](https://www.nrel.gov/docs/fy21osti/77417.pdf). ACEEE Summer Study on Energy Efficiency in Buildings, 17-21 August 2020. diff --git a/workflows/carbon_emissions.md b/workflows/carbon_emissions.md index efa6e9b6..7c32f7a4 100644 --- a/workflows/carbon_emissions.md +++ b/workflows/carbon_emissions.md @@ -2,7 +2,7 @@ layout: default title: Carbon Emissions parent: Workflows -nav_order: 5 +nav_order: 1 --- # **Carbon Emissions Reporting** diff --git a/workflows/des.md b/workflows/des.md index da8a7d96..d9d25f53 100644 --- a/workflows/des.md +++ b/workflows/des.md @@ -2,7 +2,7 @@ layout: default title: District Energy Systems (DES) parent: Workflows -nav_order: 4 +nav_order: 3 --- # District Energy Systems (DES) @@ -115,7 +115,7 @@ Visit the [developer resources page](https://docs.urbanopt.net/geojson-modelica- - Kathryn Hinkelman, Jing Wang, Chengliang Fan, Wangda Zuo, Antoine Gautier, Michael Wetter, Nicholas Long. (2021). [A Case Study on Condenser Water Supply Temperature Optimization with a District Cooling Plant.](https://doi.org/10.3384/ecp21181587) Proceedings of 14th Modelica Conference 2021, Linköping, Sweden, September 20-24, 2021, 181, 587–595. -- Allen, A., Long, N. L., Moore, N., & Elarga, H. (2021). URBANopt District Energy Systems HVAC Measures. National Renewable Energy Laboratory. [https://doi.org/10.11578/dc.20210127.1](https://doi.org/10.11578/dc.20210127.1) +- Allen, A., Long, N. L., Moore, N., & Elarga, H. (2021). [URBANopt District Energy Systems HVAC Measures](https://doi.org/10.11578/dc.20210127.1) National Renewable Energy Laboratory. - Allen, A., Henze, G., Baker, K., Pavlak Gregory, & Murphy, M. (2021). [Evaluation of Topology Optimization to Achieve Energy Savings at the Urban District Level](https://www.nrel.gov/docs/fy21osti/77625.pdf). 2021 ASHRAE Winter Conference. diff --git a/workflows/disco/disco.md b/workflows/disco/disco.md index 97aeaf0d..e22abc02 100644 --- a/workflows/disco/disco.md +++ b/workflows/disco/disco.md @@ -1,7 +1,7 @@ --- layout: default title: DISCO -nav_order: 3 +nav_order: 2 parent: Workflows --- # DISCO @@ -66,7 +66,7 @@ URBANopt CLI following the steps below: Create a DISCO project by including the `-a` flag in the create command: ```bash - uo create --project-folder --disco + uo create --project-folder --disco ``` This will create a `disco` folder in the URBANopt example project which includes DISCO specific files such diff --git a/workflows/geometry_workflows.md b/workflows/geometry_workflows.md index 1940fac7..2b816cd4 100644 --- a/workflows/geometry_workflows.md +++ b/workflows/geometry_workflows.md @@ -2,7 +2,7 @@ layout: default title: Geometry Workflows parent: Workflows -nav_order: 8 +nav_order: 4 --- The URBANopt™ project offers different options for creating building geometry to suit various diff --git a/workflows/ghp/ghp.md b/workflows/ghp/ghp.md new file mode 100644 index 00000000..9680c330 --- /dev/null +++ b/workflows/ghp/ghp.md @@ -0,0 +1,106 @@ +--- +layout: default +title: Geothermal Heat Pump (GHP) +nav_order: 5 +parent: Workflows +--- + +# Geothermal Heat Pump (GHP) Analysis + +**This workflow is available in URBANopt versions 0.11.0 and later** + +The URBANopt-Geothermal Heat Pump (GHP) workflows are used for modeling and simulation of district-scale GHP systems. URBANopt is used to calculate building loads connected to the GHP system. The building loads along with technical specifications for the GHP system, stored in the system parameter file, are used for sizing and simulations of custom district GHP systems. The installation and usage of these capabilities are described below. + +## Installation + +Run the following URBANopt CLI command to install Python and the required GHP-related dependencies: + +```bash +uo install_python +``` + +## Usage + + +In order to use the URBANopt-GHP capabilities, the example `GHP Project` can be created and run using the URBANopt CLI following the steps below: + + +1. ### Create a GHP Project + + Create a GHP project by including the `--ghe` flag (or `-g` as a shortcut) in the create command: + + ```bash + uo create --project-folder --ghe + ``` + + This will create an URBANopt example project which includes a feature file with a single pipe closed GHP network as shown in the figure below: + + ![ghp2](../../doc_files/ghp2.PNG) + + The Feature File includes the footprint area of the GHP will be used as an input for GHP sizing. + + +2. ### Create Scenario Files + + Scenario files are created next using the following command: + + ```bash + uo create --scenario-file + ``` + +3. ### Run the Project + + Run the project using the GHP feature file, and the scenario file created in the previous step: + + ```bash + uo run --feature --scenario + ``` + +4. ### Default post-process Scenario + + Post-process using the default post-processor, this generates the timeseries building loads (kW) using the `export_modelica_loads` measure and stored in the run folder for the scenario: + + ```bash + uo process --default --feature --scenario + ``` + +5. ### Create System Parameter file + + This is used to create a system parameters file that stores technical properties related to GHP components such as boreholes, soil, fluid, and pipe definitions. + + The following command can be used to create the system parameters file: + + ```bash + uo des_params --sys-param-file --feature --scenario --ghe + ``` + + The `ghe_specific_params` section within the system parameters file generated by this command stores properties for each GHP in the network. It pulls the GHP ID as well as the length and width of GHP from the feature file. + +6. ### Size GHP + + Sizing the GHP system involves calculating properties such as number of boreholes, length of boreholes, and the g-function. + + This is done using the following command: + + + ```bash + uo ghe_size --sys-param --feature --scenario + ``` + + On running this command, a new folder `ghe_dir` is created that stores sizing results such as the g-function and the ground loads for the GHP. The system parameters file is also updated with the results of sizing such as the number of boreholes and length of boreholes. + +7. ### Create Modelica Model and Modelica Directory + + This uses the URBANopt-DES module to create a Modelica package for the sized GHP network, as shown in the [DES Functionality section](../../getting_started/getting_started). It takes in the building loads, GHE sizing results, and the system parameter file with GHE-specific properties to create the Modelica package for the district thermal energy system. + + The following command is used: + + ```bash + uo des_create --sys-param --feature --des-name + ``` + +8. ### Run Modelica Models + + ```bash + uo des_run --model + ``` diff --git a/workflows/opendss/opendss.md b/workflows/opendss/opendss.md index 62055772..a3bf13d9 100644 --- a/workflows/opendss/opendss.md +++ b/workflows/opendss/opendss.md @@ -1,7 +1,7 @@ --- layout: default title: OpenDSS Converter -nav_order: 3 +nav_order: 6 parent: Workflows --- # OpenDSS Converter diff --git a/workflows/optimization.md b/workflows/optimization.md index 04adea45..5074f16e 100644 --- a/workflows/optimization.md +++ b/workflows/optimization.md @@ -2,7 +2,7 @@ layout: default title: Optimization Workflows parent: Workflows -nav_order: 9 +nav_order: 7 --- # Optimization diff --git a/workflows/photovoltaic.md b/workflows/photovoltaic.md index b432b6f9..02d639e2 100644 --- a/workflows/photovoltaic.md +++ b/workflows/photovoltaic.md @@ -2,7 +2,7 @@ layout: default title: Photovoltaic Workflows parent: Workflows -nav_order: 2 +nav_order: 8 --- # Solar Photovoltaics Workflows diff --git a/workflows/reopt/reopt.md b/workflows/reopt/reopt.md index 514f749d..c1ac1c0c 100644 --- a/workflows/reopt/reopt.md +++ b/workflows/reopt/reopt.md @@ -3,7 +3,7 @@ layout: default title: REopt has_children: true parent: Workflows -nav_order: 1 +nav_order: 9 ---
diff --git a/workflows/residential_workflows/building_inputs.md b/workflows/residential_workflows/building_inputs.md new file mode 100644 index 00000000..fd6e8802 --- /dev/null +++ b/workflows/residential_workflows/building_inputs.md @@ -0,0 +1,134 @@ +--- +layout: default +title: Building Inputs +parent: Residential Workflows +grand_parent: Workflows +nav_order: 2 +--- + +## Building Inputs + +HPXML files are built based on feature information contained in the GeoJSON file. +The [Building Types](building_types.md) section lists all the required and optional GeoJSON fields for each building type. + +Following the assignment of fields from the GeoJSON file (e.g., building type, number of stories, floor area), a number of inputs are defaulted using the OpenStudio-HPXML workflow. +Optionally, input values may be *further* refined/adjusted using either a customizable template or samples from the [ResStock™](https://www.nrel.gov/buildings/resstock.html) workflow. + +- [Default Values](#default-values) +- [Customizable Template](#customizable-template) +- [ResStock Samples](#resstock-samples) + +After all arguments are assigned input values and an HPXML file is built, a translator measure is then applied to construct an OpenStudio© building model. + +### Default Values + +The [Input Defaults](https://openstudio-hpxml.readthedocs.io/en/latest/workflow_inputs.html#input-defaults) section of the [OpenStudio-HPXML documentation](https://openstudio-hpxml.readthedocs.io/en/latest/index.html) describes how HPXML fields may be defaulted. +Defaults are generally based on **ANSI / RESNET / ICC Std. 301 (2019)**. + +For example, the air leakage infiltration rate of the building (i.e., air changes per hour at 50 Pascals obtained from a blower door measurement) is not specified using feature information from the GeoJSON file. +A default value of 3 ACH50 is used, which impacts the infiltration model. + +The air leakage infiltration rate of the building may be changed from its default value of 3 ACH50 (e.g., to 7 ACH50 or 20 ACH50) using either approach described in the following [Customizable Template](#customizable-template) and [ResStock Samples](#resstock-samples) sections. + +### Customizable Template + +An optional template enumeration may be specified for each feature in the GeoJSON file. +See the [GeoJSON Schema](other_details#geojson-schema) optional fields section for the specific template field name. +The assignment of various argument values contained in *TSV lookup files* depend on the specified template enumeration. +Customizable template enumerations that are applicable to residential buildings: + +- `Residential IECC - Customizable Template Sep 2020` +- `Residential IECC - Customizable Template Apr 2022` + +for ` = 2006, 2009, 2012, 2015, 2018`. + +The various arguments that may be assigned input values use mappings contained in the following [TSV lookup files](https://github.com/urbanopt/urbanopt-example-geojson-project/tree/develop/example_project/mappers/residential/template/iecc): + +- clothes_dryer.tsv +- clothes_washer.tsv +- cooling_system.tsv +- dishwasher.tsv +- enclosure.tsv +- heat_pump.tsv +- heating_system.tsv +- mechanical_ventilation.tsv +- refrigerator.tsv +- water_heater.tsv + +Argument values found in these lookup files span across the following categories: + +- enclosure (insulation levels, air leakage, etc.) +- heating/cooling systems (types, efficiencies, etc.) +- appliances (refrigerator, clothes washer, etc.) +- mechanical ventilation +- water heating + +All argument values for the previous categories may be customized by manually adjusting values in the lookup files, or a new customizable template with unique argument values may be created as described below. +The enumeration names include "Residential IECC 20XX" because a variety of enclosure, window, duct insulation, and whole-home air leakage assumptions are based on the different IECC model code years to illustrate how templates can be used to approximate different levels of efficiency. +Note that not all possible assumptions have been aligned with IECC requirements (e.g., see above regarding defaults), but the users can further customize these templates as needed for specific projects. + +The residential workflows in URBANopt are designed to be flexible and extensible to adapt to specific user projects. +The building models are created on the basis of default assumptions made for different building components within lookup files, grouped together within a template, and assigned to the building feature in the feature file. +To modify the models, these templates and the underlying assumptions can be customized, or a new template with unique assumptions can be created. +The URBANopt example project includes alternate customizable "Residential IECC 20XX - Customizable Template Apr 2022" templates (e.g., for modeling homes where some types appliances are not present and/or efficiency of certain appliances/equipment needs to be adjusted) and illustrates how these could be assigned to the building features. + +The specific assumptions made in these customized templates for different building equipment in the lookup files are: + +- Clothes Dryer: The location is updated to be "none" and it is assumed that no clothes dryer is present. +- Clothes Washer: The location is updated to be "none" and it is assumed that no clothes dryer is present. +- Dishwasher: The location is updated to be "none" and it is assumed that no clothes dryer is present. +- Refrigerator: The efficiency of the appliance is modified. +- Water heater: The efficiency of the appliance is modified. + +This customized template is assigned to the low-rise residential building features in the [alternate combined example project feature file](https://github.com/urbanopt/urbanopt-cli/blob/e7d29764eb9ae837078f92a488adb783a3e52616/example_files/example_project_combined.json). +It is to be noted that these values are meant to be representative to illustrate how templates can be used to customize the workflow for different communities and are not based on an actual community or formal study. +Users should ensure that specific assumptions in their templates are accurate for the homes/communities they are modeling. + +### ResStock Samples + +As of v0.13.0, optional boolean and path fields may be set in GeoJSON features to indicate assignment of argument values corresponding to mapped ResStock parameters. +See the [GeoJSON Schema](other_details#geojson-schema) optional fields section for specific boolean and path field names. +The path field should be either a: + +- relative file path that references a ResStock **buildstock CSV file** directly sampled from a project, or +- relative file path that references a ResStock **buildstock CSV file** mapping GeoJSON feature ID to set of ResStock parameters. + +The buildstock CSV file stores a collection of Parameter/Option pairs, organized by ResStock Building ID, that have been sampled from a set of statistical distributions derived from U.S. residential housing stock characterization data. +An example of a buildstock CSV file is given [here](https://github.com/NREL/resstock/blob/develop/test/base_results/baseline/annual/buildstock.csv). +Each sample (i.e., row of the buildstock CSV file) represents several individual dwelling units within the actual housing stock. + +ResStock maps individual dwelling unit samples into OpenStudio-HPXML argument values using the: + +- [options_lookup.tsv](https://github.com/NREL/resstock/blob/develop/resources/options_lookup.tsv) file +- [ResStockArguments](https://github.com/NREL/resstock/tree/develop/measures/ResStockArguments) OpenStudio measure + +Each row of the buildstock CSV file, therefore, becomes a building model created from mapped model input values. +The basic OpenStudio-HPXML/ResStock/URBANopt workflow is depicted in the flow chart below. + +![os-hpxml-resstock-workflow](../../doc_files/os-hpxml-resstock-workflow.png) + +URBANopt connects to ResStock by either: + +- matching sampled buildstock CSV file sample row(s) to GeoJSON feature properties (e.g., building type, number of stories, floor area), or +- matching the row of the buildstock CSV file by GeoJSON feature ID + +Once the appropriate ResStock Building ID from the buildstock CSV file is identified, argument values corresponding to sampled Parameter/Option pairs can be assigned. +Note that some argument assignments from the options_lookup.tsv file are ignored if they conflict with defined properties in the GeoJSON feature. +For example, the "County" parameter maps various weather-related arguments, but location is already defined in the GeoJSON file. + +Previously defaulted input values are thus refined using argument value assignments corresponding to representative ResStock samples. +In the case of the air leakage infiltration rate example from above, ResStock explicitly samples "ACH50" options for its "Infiltration" parameter. +If the identified ResStock Building ID has a corresponding sampled "7 ACH50" option, this would result in overriding the default value of 3 ACH50 with 7 ACH50. +The [Housing Characteristics](https://resstock.readthedocs.io/en/latest/workflow_inputs/characteristics.html#housing-characteristics) section of the [ResStock documentation](https://resstock.readthedocs.io/en/latest/index.html) describes all parameters sampled by ResStock. + +ResStock samples are defined at the individual dwelling unit level. +Therefore, with the exception of stochastic occupancy schedules, this workflow duplicates dwelling units for Single-Family Attached and Low-Rise Multifamily buildings. +Building units have variation across schedules but not in terms of their: + +- attic type (e.g., vented, adiabatic) +- foundation type (e.g., slab, adiabatic) +- orientation (e.g., North, South) +- location (e.g., corner unit, top unit) + +After each feature's HPXML file is built (containing 1 or more dwelling units), OpenStudio-HPXML's [HPXMLtoOpenStudio](https://github.com/NREL/OpenStudio-HPXML/tree/master/HPXMLtoOpenStudio) OpenStudio measure is applied to translate and construct an OpenStudio building model. +The building model is then simulated using OpenStudio/EnergyPlus. diff --git a/workflows/residential_workflows/building_occupancy.md b/workflows/residential_workflows/building_occupancy.md new file mode 100644 index 00000000..69af5559 --- /dev/null +++ b/workflows/residential_workflows/building_occupancy.md @@ -0,0 +1,40 @@ +--- +layout: default +title: Building Occupancy +parent: Residential Workflows +grand_parent: Workflows +nav_order: 3 +--- + +## Building Occupancy + +The user has control over both occupant-related schedule types and occupancy calculation types: + +- [Schedule Types](#schedule-types) +- [Calculation Types](#calculation-types) + +### Schedule Types + +Occupant-related schedules can be either defaulted (smooth) or stochastically generated, and may vary either building-to-building or unit-to-unit. +The default behavior is to use stochastically generated schedules that vary unit-to-unit, but the user has control to both use defaulted schedules and vary them building-to-building. +Note that there are runtime impacts associated with using stochastically generated schedules and for varying schedules unit-to-unit. + +Stochastic schedules are generated using time-inhomogenous Markov chains derived from American Time Use Survey data, supplemented with sampling duration and power level from NEEA RBSA data, as well as DHW draw duration and flow rate data from Aquacraft/AWWA data. + +In terms of repeatability, stochastic schedules generation uses a pseudo-random number generator that takes a seed as an argument. +The seed is determined by the index of a given feature relative to all features in the GeoJSON, and then multiplied by the unit number within the building. +For schedules that vary by building, the schedules that correspond to the first unit are used for all units of the building. +Relocating a feature's position within a GeoJSON would change the seed argument for that building. + +### Calculation Types + +Occupancy-based loads (i.e., plug loads, appliances, hot water, etc.) can be calculated through either: + +1. an asset calculation, or +1. an operational calculation. + +The default behavior is to perform an asset calculation, but the user has control to enable an operational calculation. + +Asset calculations are performed using number of bedrooms and/or conditioned floor area. + +Operational calculations are performed using an adjustment for the number of occupants. \ No newline at end of file diff --git a/workflows/residential_workflows/building_types.md b/workflows/residential_workflows/building_types.md new file mode 100644 index 00000000..08aa1cf4 --- /dev/null +++ b/workflows/residential_workflows/building_types.md @@ -0,0 +1,179 @@ +--- +layout: default +title: Building Types +parent: Residential Workflows +grand_parent: Workflows +has_children: true +nav_order: 1 +has_toc: false +--- + +## Building Types + +Currently, the following residential building types are supported: + +- [Single-Family Detached](#single-family-detached) +- [Single-Family Attached](#single-family-attached) +- [Low-Rise Multifamily](#low-rise-multifamily)[^1] + +Only the [Baseline Scenario](../../resources/scenarios/baseline.md) and [High Efficiency Scenario](../../resources/scenarios/highefficiency.md) are supported at this time; any additional mappers will need to be updated manually. + +Note that the modeling capabilities for these building types are currently in Beta mode. +This means that testing and development is still in progress, and user feedback is welcome. + +[^1]: Mid-Rise and High-Rise Multifamily building prototypes can be found in the commercial building workflows). + +### Single-Family Detached + +Consider the highlighted "Single-Family Detached" building footprint with the following high-level URBANopt™ GeoJSON inputs: + +* 1 story above ground +* unvented crawlspace foundation +* vented attic +* 2 car garage + +![single_family_detached](../../doc_files/single-family-detached-footprint.jpg) + +An example 3D rendering of the single-family detached building is shown below. + +![single_family_detached](../../doc_files/single-family-detached-1.jpg) + +Note that the footprint of the modeled unit, less the garage, is always rectangular even though the GeoJSON footprint may not be. +See [Assumptions](other_details#assumptions) for more information. + +The 3D building surfaces stored in HPXML and OSM models represent the area and orientation of ground and exterior exposure of surfaces, but do not represent their position relative to each other. +An example geometry rendering for a translated HPXML file is given below. + +![single_family_detached](../../doc_files/single-family-detached-2.jpg) + +An example "Single-Family Detached" building feature snippet is shown below. + + ```json + { + "type": "Feature", + "properties": { + "id": "14", + "name": "Residential 1", + "type": "Building", + "building_type": "Single-Family Detached", + "floor_area": 3055, + "footprint_area": 3055, + "number_of_stories_above_ground": 1, + "number_of_stories": 1, + "number_of_bedrooms": 3, + "foundation_type": "crawlspace - unvented", + "attic_type": "attic - vented", + "system_type": "Residential - furnace and central air conditioner", + "heating_system_fuel_type": "natural gas", + "onsite_parking_fraction": 1, + "template": "Residential IECC 2015 - Customizable Template Sep 2020" + } + ``` + +### Single-Family Attached + +Consider the highlighted "Single-Family Attached" building footprint with the following high-level URBANopt™ GeoJSON inputs: + +* 2 stories above ground +* slab foundation +* vented attic +* 4 living units +* no rear units + +![single_family_attached](../../doc_files/single-family-attached-footprint.jpg) + +The number of living units are used to determine the position (i.e., horizontal location) of individual living units contained in the building. +By determining the position of individual units relative the whole building, types and boundary conditions of surfaces (e.g., adiabatic) can be stored in the HPXML. + +Example 3D renderings for a single unit from the building is shown below. +This unit is designated as having a "Right" horizontal location (when viewing from the front). +You can see outside boundary conditions of "Outdoors" on one facade, and "Adiabatic" on the opposite facade. + +![single_family_attached](../../doc_files/single-family-attached-1-1.jpg) +![single_family_attached](../../doc_files/single-family-attached-1-2.jpg) + +Note that the footprint of the modeled unit is always rectangular even though the GeoJSON footprint may not be. +See [Assumptions](other_details#assumptions) for more information. + +For each unit of the building, an HPXML and OSM model is constructed. +These OSM models are merged into a single OSM model, as shown below. + +![single_family_attached](../../doc_files/single-family-attached-2.jpg) + +An example "Single-Family Attached" building feature snippet is shown below. + + ```json + { + "id": "17", + "name": "Residential 4", + "type": "Building", + "building_type": "Single-Family Attached", + "floor_area": 18320, + "footprint_area": 9160, + "number_of_stories_above_ground": 2, + "number_of_stories": 2, + "number_of_bedrooms": 6, + "foundation_type": "slab", + "attic_type": "attic - vented", + "system_type": "Residential - furnace and room air conditioner", + "heating_system_fuel_type": "fuel oil", + "number_of_residential_units": 4, + "template": "Residential IECC 2015 - Customizable Template Sep 2020" + } + ``` + +### Low-Rise Multifamily + +Consider the highlighted "Low-Rise Multifamily" building footprint with the following high-level URBANopt™ GeoJSON inputs: + +* 2 stories above ground +* slab foundation +* flat roof +* 8 living units +* double exterior corridor + +![multifamily](../../doc_files/multifamily-footprint.jpg) + +The number of living units and stories above ground are used to determine the position (i.e., horizontal location and vertical level) of individual living units contained in the building. +By determining the position of individual units relative the whole building, types and boundary conditions of surfaces (e.g., adiabatic) can be stored in the HPXML. + +Example 3D renderings for a single unit from the building is shown below. +This unit is designated as having a "Left" horizontal location and a "Top" vertical level (when viewing from the front). +You can see outside boundary conditions of "Outdoors" on the roof and one facade, and "Adiabatic" on the floor and opposite facade. + +![multifamily](../../doc_files/multifamily-1-1.jpg) +![multifamily](../../doc_files/multifamily-1-2.jpg) +![multifamily](../../doc_files/multifamily-1-3.jpg) +![multifamily](../../doc_files/multifamily-1-4.jpg) + +Note that the footprint of the modeled unit is always rectangular even though the GeoJSON footprint may not be. +See [Assumptions](other_details#assumptions) for more information. + +For each unit of the building, an HPXML and OSM model is constructed. +These OSM models are merged into a single OSM model, as shown below. + +![multifamily](../../doc_files/multifamily-2.jpg) + +An example "Low-Rise Multifamily" building feature snippet is shown below. + + ```json + { + "type": "Feature", + "properties": { + "id": "18", + "name": "Residential 5", + "type": "Building", + "building_type": "Multifamily", + "floor_area": 28636, + "footprint_area": 14318, + "number_of_stories_above_ground": 2, + "number_of_stories": 2, + "number_of_bedrooms": 16, + "foundation_type": "slab", + "attic_type": "flat roof", + "system_type": "Residential - furnace and room air conditioner", + "heating_system_fuel_type": "wood", + "number_of_residential_units": 8, + "template": "Residential IECC 2015 - Customizable Template Sep 2020" + } + ``` diff --git a/workflows/residential_workflows/customization.md b/workflows/residential_workflows/customization.md deleted file mode 100644 index da604baa..00000000 --- a/workflows/residential_workflows/customization.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -layout: default -title: Customization -parent: Residential Workflows -has_children: true -nav_order: 6 -has_toc: false ---- - -# Residential Workflows Customization - - -The residential workflows in URBANopt are designed to be flexible and extensible to adapt to specific user -projects. The building models are created on the basis of default assumptions -made for different building components within lookup files, grouped together within a template, and assigned to the -building feature in the feature file as described under [customizable template](https://docs.urbanopt.net/workflows/residential_workflows/residential_workflows.html#customizable-template). To modify the models, these templates and the underlying assumptions -can be customized, or a new template with unique assumptions can be created. The URBANopt example -project includes alternate customizable templates (e.g., for modeling homes where some types appliances are not present and/or efficiency of certain appliances/equipment needs to be adjusted) and illustrates how these could be assigned to the building features. - -The following additional customizable templates are included: - -- `Residential IECC 2006 - Customizable Template Apr 2022` -- `Residential IECC 2009 - Customizable Template Apr 2022` -- `Residential IECC 2012 - Customizable Template Apr 2022` -- `Residential IECC 2015 - Customizable Template Apr 2022` -- `Residential IECC 2018 - Customizable Template Apr 2022` - -The specific assumptions made in these customized templates for different building equipment in the -lookup files are: - -- Clothes Dryer : The location is updated to be 'none' and it is assumed that no clothes dryer is - present. - -- Clothes Washer: The location is updated to be 'none' and it is assumed that no clothes dryer is - present. - -- Dishwasher: The location is updated to be 'none' and it is assumed that no clothes dryer is - present. - -- Refrigerator: The efficiency of the appliance is modified. - -- Water heater: The efficiency of the appliance is modified. - -This customized template is assigned to the low-rise residential building features in the [alternate -combined example project feature file](https://github.com/urbanopt/urbanopt-cli/blob/e7d29764eb9ae837078f92a488adb783a3e52616/example_files/example_project_combined.json). It is to be noted, that these values are meant to be representative -to illustrate how templates can be used to customize -the workflow for different communities and are not based on an actual community or formal study. Users should ensure that specific assumptions in their templates are accurate for the homes/communities they are modeling. diff --git a/workflows/residential_workflows/multifamily.md b/workflows/residential_workflows/multifamily.md deleted file mode 100644 index bdd3c6c9..00000000 --- a/workflows/residential_workflows/multifamily.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -layout: default -title: Low-Rise Multifamily -parent: Residential Workflows -grand_parent: Workflows -nav_order: 3 ---- - -## Low-Rise Multifamily - -Consider the highlighted "Low-Rise Multifamily" building footprint with the following high-level URBANopt™ GeoJSON inputs: - -* 2 stories above ground -* slab foundation -* flat roof -* 8 living units -* double exterior corridor - -![multifamily](../../doc_files/multifamily-footprint.jpg) - -The number of living units and stories above ground are used to determine the position (i.e., horizontal location and vertical level) of individual living units contained in the building. -By determining the position of individual units relative the whole building, types and boundary conditions of surfaces (e.g., adiabatic) can be stored in the HPXML. - -Example 3D renderings for a single unit from the building is shown below. -This unit is designated as having a "Left" horizontal location and a "Top" vertical level (when viewing from the front). -You can see outside boundary conditions of "Outdoors" on the roof and one facade, and "Adiabatic" on the floor and opposite facade. - -![multifamily](../../doc_files/multifamily-1-1.jpg) -![multifamily](../../doc_files/multifamily-1-2.jpg) -![multifamily](../../doc_files/multifamily-1-3.jpg) -![multifamily](../../doc_files/multifamily-1-4.jpg) - -Note that the footprint of the modeled unit is always rectangular even though the GeoJSON footprint may not be. See [Other Assumptions](residential_workflows#other-assumptions) for more information. - -For each unit of the building, an HPXML and OSM model is constructed. -These OSM models are merged into a single OSM model, as shown below. - -![multifamily](../../doc_files/multifamily-2.jpg) - - -### Modeling Notes - -- "Low-Rise Multifamily" home models may be heated only, cooled only, or both heated and cooled. - - Partial Conditioning: heating and cooling may be applied to just a portion of the living space of the home or to the entire living space. Representation of partial conditioning of the living space of a home is accomplished by adding ideal air load system to heat and cool the unconditioned portion of the living area. In this situation, district heating or cooling loads may show up in end uses for the home. - - Undersized Mechanical System: District heating or cooling loads may also show up in end uses when a designed mechanical system cannot meet the load required to maintain thermostat temperatures. An example would be an evaporative cooling system in a hot humid climate. - - For both the partially conditioned and undersized examples, it is possible for reporting or post processing to filter out these unintended district heating and cooling loads. -- It is important to know, that unlike the commercial models that will result in unmet heating or cooling hours, the residential models will not have any unmet heating or cooling hours. To understand how the HVAC system is conditioning for "Low-Rise Multifamily" home models, users should look at district heating and cooling loads. - - -### GeoJSON Schema - -The [URBANopt GeoJSON schema](https://github.com/urbanopt/urbanopt-geojson-gem/blob/develop/lib/urbanopt/geojson/schema/building_properties.json) differentiates between sets of required and optional fields for "Low-Rise Multifamily" residential buildings: - -Required fields: - -| Field | Type | Enums | Notes | -| ----------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| floor_area | number | | Total conditioned floor area. | -| footprint_area | number | | First floor conditioned floor area. | -| number_of_stories_above_ground| integer | | | -| number_of_stories | integer | | Includes foundations. | -| number_of_residential_units | integer | | Divisible by stories. | -| number_of_bedrooms | integer | | Must be > 0. | -| foundation_type | string | (1) slab
(2) crawlspace - vented
(3) crawlspace - unvented
(4) basement - unconditioned
(5) ambient | Invalid:
(1) crawlspace - conditioned
(2) basement - conditioned | -| attic_type | string | (1) attic - vented
(2) attic - unvented
(3) flat roof | Invalid:
(1) attic - conditioned | - -Optional fields: - -| Field | Type | Enums | Notes | -| ----------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| roof_type | string | (1) Gable
(2) Hip | NA when attic type is flat roof. | -| occupancy_calculation_type | string | (1) asset
(2) operational | | -| number_of_occupants | integer | | For operational calculations. | -| system_type | string | (1) electric resistance
(2) furnace
(3) boiler
(4) central air conditioner
(5) room air conditioner
(6) evaporative cooler
(7) air-to-air heat pump
(8) mini-split heat pump
(9) ground-to-air-heat-pump | | -| system_type | string | (1) electric resistance
(2) furnace
(3) boiler
(4) central air conditioner
(5) room air conditioner
(6) evaporative cooler
(7) air-to-air heat pump
(8) mini-split heat pump
(9) ground-to-air-heat-pump | | -| heating_system_fuel_type | string | (1) electricity
(2) natural gas
(3) fuel oil
(4) propane
(5) wood | | -| template | string | | See [Customizable Template](residential_workflows#customizable-template) | -| hpxml_directory | string | | Relative to xml_building. Most required fields are then optional. | - -An example "Low-Rise Multifamily" building feature snippet is shown below. - - ```json - { - "type": "Feature", - "properties": { - "id": "18", - "name": "Residential 5", - "type": "Building", - "building_type": "Multifamily", - "floor_area": 28636, - "footprint_area": 14318, - "number_of_stories_above_ground": 2, - "number_of_stories": 2, - "number_of_bedrooms": 16, - "foundation_type": "slab", - "attic_type": "flat roof", - "system_type": "Residential - furnace and room air conditioner", - "heating_system_fuel_type": "wood", - "number_of_residential_units": 8, - "template": "Residential IECC 2015 - Customizable Template Sep 2020" - } - ``` diff --git a/workflows/residential_workflows/single_family_detached.md b/workflows/residential_workflows/other_details.md similarity index 59% rename from workflows/residential_workflows/single_family_detached.md rename to workflows/residential_workflows/other_details.md index a24f148d..0cf7e803 100644 --- a/workflows/residential_workflows/single_family_detached.md +++ b/workflows/residential_workflows/other_details.md @@ -1,61 +1,48 @@ --- layout: default -title: Single-Family Detached +title: Other Details parent: Residential Workflows grand_parent: Workflows -nav_order: 1 +nav_order: 4 --- -## Single-Family Detached +## Other Details -Consider the highlighted "Single-Family Detached" building footprint with the following high-level URBANopt™ GeoJSON inputs: - -* 1 story above ground -* unvented crawlspace foundation -* vented attic -* 2 car garage - -![single_family_detached](../../doc_files/single-family-detached-footprint.jpg) - -An example 3D rendering of the single-family detached building is shown below. - -![single_family_detached](../../doc_files/single-family-detached-1.jpg) - -Note that the footprint of the modeled unit, less the garage, is always rectangular even though the GeoJSON footprint may not be. See [Other Assumptions](residential_workflows#other-assumptions) for more information. - -The 3D building surfaces stored in HPXML and OSM models represent the area and orientation of ground and exterior exposure of surfaces, but do not represent their position relative to each other. -An example geometry rendering for a translated HPXML file is given below. - -![single_family_detached](../../doc_files/single-family-detached-2.jpg) +Other modeling details are described for the following categories: +- [Modeling Notes](#modeling-notes) +- [GeoJSON Schema](#geojson-schema) +- [Assumptions](#assumptions) ### Modeling Notes -- "Single-Family Detached" home models may contain unconditioned non-living spaces that are included as part of the total building area, such as a garage. As a result energy use intensities (EUIs) for homes, often calculated in units of kBtu/sqft/yr, will vary based on the unconditioned floor area if total building area is used for the calculation. Alternatively, conditioned floor area can be used for such calculations. -- "Single-Family Detached" home models may be heated only, cooled only, or both heated and cooled. +- The building footprint drawn and contained in the GeoJSON does not determine the footprint of individual modeled units. +- Floor area is divided by the number of residential units to determine the floor area of each individual unit. +- Individual footprints are determined using this unit floor area and an aspect ratio of 2 (i.e., front/back walls are twice as long as left/right walls). +- Single-Family Detached home models may contain unconditioned non-living spaces that are included as part of the total building area, such as a garage. As a result energy use intensities (EUIs) for homes, often calculated in units of kBtu/sqft/yr, will vary based on the unconditioned floor area if total building area is used for the calculation. Alternatively, conditioned floor area can be used for such calculations. +- Home models for all building types may be heated only, cooled only, or both heated and cooled. - Partial Conditioning: heating and cooling may be applied to just a portion of the living space of the home or to the entire living space. Representation of partial conditioning of the living space of a home is accomplished by adding ideal air load system to heat and cool the unconditioned portion of the living area. In this situation, district heating or cooling loads may show up in end uses for the home. - Undersized Mechanical System: District heating or cooling loads may also show up in end uses when a designed mechanical system cannot meet the load required to maintain thermostat temperatures. An example would be an evaporative cooling system in a hot humid climate. - For both the partially conditioned and undersized examples, it is possible for reporting or post processing to filter out these unintended district heating and cooling loads. -- It is important to know, that unlike the commercial models that will result in unmet heating or cooling hours, the residential models will not have any unmet heating or cooling hours. To understand how the HVAC system is conditioning for "Single-Family Detached" home models, users should look at district heating and cooling loads. - +- It is important to know, that unlike the commercial models that will result in unmet heating or cooling hours, the residential models will not have any unmet heating or cooling hours. To understand how the HVAC system is conditioning for home models, users should look at district heating and cooling loads. ### GeoJSON Schema -The [URBANopt GeoJSON schema](https://github.com/urbanopt/urbanopt-geojson-gem/blob/develop/lib/urbanopt/geojson/schema/building_properties.json) differentiates between sets of required and optional fields for "Single-Family Detached" residential buildings: +The [URBANopt GeoJSON schema](https://github.com/urbanopt/urbanopt-geojson-gem/blob/develop/lib/urbanopt/geojson/schema/building_properties.json) differentiates between sets of **required** and **optional** fields for Single-Family Detached, Single-Family Attached, and Low-Rise Multifamily residential buildings. -Required fields: +**Required** fields: -| Field | Type | Enums | Notes | +| Field | Data Type | Enums | Notes | | ----------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | floor_area | number | | Total conditioned floor area. | | footprint_area | number | | First floor conditioned floor area. | | number_of_stories_above_ground| integer | | | | number_of_stories | integer | | Includes foundations. | | number_of_bedrooms | integer | | Must be > 0. | -| foundation_type | string | (1) slab
(2) crawlspace - vented
(3) crawlspace - unvented
(4) crawlspace - conditioned
(5) basement - unconditioned
(6) basement - conditioned
(7) ambient | | -| attic_type | string | (1) attic - vented
(2) attic - unvented
(3) attic - conditioned
(4) flat roof | Stories > 1 for conditioned attics. | +| foundation_type | string | (1) slab
(2) crawlspace - vented
(3) crawlspace - unvented
(4) crawlspace - conditioned
(5) basement - unconditioned
(6) basement - conditioned
(7) ambient | Excluding (4) and (6) for Low-Rise Multifamily. | +| attic_type | string | (1) attic - vented
(2) attic - unvented
(3) attic - conditioned
(4) flat roof | Excluding (3) for Low-Rise Multifamily. Stories > 1 for (3). | -Optional fields: +**Optional** fields: | Field | Type | Enums | Notes | | ----------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | @@ -64,30 +51,47 @@ Optional fields: | number_of_occupants | integer | | For operational calculations. | | system_type | string | (1) electric resistance
(2) furnace
(3) boiler
(4) central air conditioner
(5) room air conditioner
(6) evaporative cooler
(7) air-to-air heat pump
(8) mini-split heat pump
(9) ground-to-air-heat-pump | | | heating_system_fuel_type | string | (1) electricity
(2) natural gas
(3) fuel oil
(4) propane
(5) wood | | -| onsite_parking_fraction | number | (1) No (0)
(2) Yes (1) | | -| template | string | | See [Customizable Template](residential_workflows#customizable-template) | -| hpxml_directory | string | | Relative to xml_building. Most required fields are then optional. | - -An example "Single-Family Detached" building feature snippet is shown below. - - ```json - { - "type": "Feature", - "properties": { - "id": "14", - "name": "Residential 1", - "type": "Building", - "building_type": "Single-Family Detached", - "floor_area": 3055, - "footprint_area": 3055, - "number_of_stories_above_ground": 1, - "number_of_stories": 1, - "number_of_bedrooms": 3, - "foundation_type": "crawlspace - unvented", - "attic_type": "attic - vented", - "system_type": "Residential - furnace and central air conditioner", - "heating_system_fuel_type": "natural gas", - "onsite_parking_fraction": 1, - "template": "Residential IECC 2015 - Customizable Template Sep 2020" - } - ``` +| onsite_parking_fraction | number | (1) No (0)
(2) Yes (1) | For Single-Family Detached only. | +| hpxml_directory | string | | Relative to the ``xml_building`` folder. Required fields become optional. | +| template | string | | See [Customizable Template](building_inputs.md#customizable-template) | +| characterize_residential_buildings_from_buildstock_csv | string | | See [ResStock Samples](building_inputs.md#resstock-samples) | +| resstock_buildstock_csv_path | string | | See [ResStock Samples](building_inputs.md#resstock-samples) | +| uo_buildstock_mapping_csv_path | string | | See [ResStock Samples](building_inputs.md#resstock-samples) | + +### Assumptions + +A summary of modeling assumptions baked into the baseline mapper is given below. +In the future, updates/improvements could be made to expose these arguments as inputs to the models. +For example, aspect ratio could be either user-defined or determined from the drawn building footprint. +Another example is allowing building orientation to be user-defined, or determining it based on the "front" of the building. + +#### Geometry: Aspect Ratio +The aspect ratio of individual units of the building is assumed to be 2. + +#### Geometry: Foundations +For buildings with a crawlspace foundation, the height of the foundation is assumed to be 3 ft. +For buildings with a basement or ambient foundation, the height of the foundation is assumed to be 8 ft. + +#### Geometry: Walls +The average height of walls adjacent to living space is 8 ft. + +#### Geometry: Neighbors +It is assumed that buildings have no neighbors. + +#### Geometry: Orientation +For Single-Family Detached and Single-Family Attached buildings, 100% of the building units are oriented to the South. +For Low-Rise Multifamily buildings, 50% of the building units are oriented to the South while the other 50% are oriented to the North. + +#### Geometry: Garages +For Single-Family Detached buildings with garages, the size of the garage depends on the floor area. +The garage is assumed to be a 1-car (12 ft wide) for buildings 2500 ft2 or less, and 2-car (24 ft wide) for buildings greater than 2500 ft2. +The garage is also assumed to protrude from the building 100% (i.e., no portion of it is tucked within the building). + +#### Geometry: Corridor +For Low-Rise Multifamily buildings, the corridor is assumed to be a "Double Exterior" corridor (i.e., entrances to individual units are from the exterior of the building). + +#### Fuel Types: Appliances +The fuel type of the cooking range, oven, and clothes dryer is assumed to match the fuel type of the heating system. + +#### Fuel Types: Water Heating +The fuel type of the water heater is assumed to match the fuel type of the heating system. \ No newline at end of file diff --git a/workflows/residential_workflows/residential_workflows.md b/workflows/residential_workflows/residential_workflows.md index 1f721fd9..b7f8088d 100644 --- a/workflows/residential_workflows/residential_workflows.md +++ b/workflows/residential_workflows/residential_workflows.md @@ -3,157 +3,24 @@ layout: default title: Residential Workflows parent: Workflows has_children: true -nav_order: 7 +nav_order: 10 has_toc: false --- # Residential Workflows -Low-rise residential building energy models in URBANopt™ are created using the [**OpenStudio-HPXML**](https://github.com/NREL/OpenStudio-HPXML) workflow. +Low-rise residential building energy models in URBANopt™ are created using the [OpenStudio-HPXML](https://github.com/NREL/OpenStudio-HPXML) workflow. For every residential building feature found in the GeoJSON file, either: -1. an [HPXML](https://hpxml.nrel.gov) file is built to represent each living unit of the building, or -1. a set of pre-built HPXML files is used to represent each of the living units of the building. +1. an [HPXML](https://hpxml.nrel.gov) file is built to represent living unit(s) of the building, or +1. a pre-built HPXML file is used to represent living unit(s) of the building. -For example, in the case of a single-family detached building one HPXML file is built to represent the single unit. -HPXML files are built based on feature information contained in the GeoJSON file as well as on sets of default assumptions contained in the following [lookup files](https://github.com/urbanopt/urbanopt-example-geojson-project/tree/develop/example_project/mappers/residential): +For example, in the case of a single-family detached building one HPXML file is built to represent the single dwelling unit. +In the case of a multifamily building one HPXML file is built containing multiple dwelling units. -* clothes_dryer.tsv -* clothes_washer.tsv -* cooling_system.tsv -* dishwasher.tsv -* enclosure.tsv -* heat_pump.tsv -* heating_system.tsv -* mechanical_ventilation.tsv -* exhaust.tsv -* refrigerator.tsv -* water_heater.tsv +The following sections describe the types of buildings supported by this workflow and how input values are assigned to various arguments. -Argument values found in these lookup files span across the following categories: - -* enclosure (insulation levels, air leakage, etc.) -* HVAC systems (heating/cooling types, efficiencies, etc.) -* appliances (refrigerator, clothes washer, etc.) -* ventilation (mechanical, exhaust) -* water heater - -See the [Customizable Template](#customizable-template) section below for more information on controlling how these assumptions are made. - -A translator measure is then applied to each HPXML file to construct an OpenStudio© building model. - -## Supported Building Types - -Currently, the following residential building types are supported: - -- [**Single-Family Detached**](./single_family_detached) -- [**Single-Family Attached**](./single_family_attached) -- [**Low-Rise Multifamily**](./multifamily)[^1] - -Only the *Baseline* and *High Efficiency* Scenarios are supported at this time; any additional mappers will need to be updated manually. - -Note that the modeling capabilities for these building types are currently in Beta mode. -This means that testing and development is still in progress, and user feedback is welcome. - -[^1]: Mid-Rise and High-Rise Multifamily building prototypes can be found in the commercial building workflows). - -## Customizable Template - -An optional template enumeration may be specified for each feature in the GeoJSON. -Enumerations that are applicable to residential buildings: - -- `Residential IECC 2006 - Customizable Template Sep 2020` -- `Residential IECC 2009 - Customizable Template Sep 2020` -- `Residential IECC 2012 - Customizable Template Sep 2020` -- `Residential IECC 2015 - Customizable Template Sep 2020` -- `Residential IECC 2018 - Customizable Template Sep 2020` -- `Residential IECC 2006 - Customizable Template Apr 2022` -- `Residential IECC 2009 - Customizable Template Apr 2022` -- `Residential IECC 2012 - Customizable Template Apr 2022` -- `Residential IECC 2015 - Customizable Template Apr 2022` -- `Residential IECC 2018 - Customizable Template Apr 2022` - -If no template enumeration is specified, argument values will be defaulted according to the [documentation](https://openstudio-hpxml.readthedocs.io/en/latest/workflow_inputs.html) for the OpenStudio-HPXML workflow. -In general, these defaults are based on **ANSI / RESNET / ICC Std. 301 (2006)**. - -All argument values for the previous categories may be customized by manually adjusting values in -the lookup files, or a new customizable template with unique argument values may be created as -described under [customization](customization.md). -The enumeration names include "Residential IECC 20XX" because a variety of enclosure, window, duct insulation, and whole-home air leakage assumptions are based on the different IECC model code years to illustrate how templates can be used to approximate different levels of efficiency. -Note that not all possible assumptions have been aligned with IECC requirements (e.g., see above regarding defaults), but the users can further customize these templates as needed for specific projects. - -## Occupancy - -The user has control over both occupant-related schedule types and the occupancy calculation type. - -### Schedules - -Occupant-related schedules can be either defaulted or stochastically generated, and may vary either building-to-building or unit-to-unit. -The default behavior is to use stochastically generated schedules that vary unit-to-unit, but the user has control to both use defaulted schedules and vary them building-to-building. -Note that there are runtime impacts associated with using stochastically generated schedules and for varying schedules unit-to-unit. - -Stochastic schedules are generated using time-inhomogenous Markov chains derived from American Time Use Survey data, supplemented with sampling duration and power level from NEEA RBSA data, as well as DHW draw duration and flow rate data from Aquacraft/AWWA data. - -In terms of repeatability, stochastic schedules generation uses a pseudo-random number generator that takes a seed as an argument. -The seed is determined by the index of a given feature relative to all features in the GeoJSON, and then multiplied by the unit number within the building. -For schedules that vary by building, the schedules that correspond to the first unit are used for all units of the building. -Relocating a feature's position within a GeoJSON would change the seed argument for that building. - -### Calculation Type - -Occupancy-based loads (i.e., plug loads, appliances, hot water, etc.) can be calculated through either: - -1. an asset calculation, or -1. an operational calculation. - -The default behavior is to perform an asset calculation, but the user has control to enable an operational calculation. - -Asset calculations are performed using number of bedrooms and/or conditioned floor area. - -Operational calculations are performed using an adjustment for the number of occupants. - -## Other Assumptions - -The building footprint drawn and contained in the GeoJSON does not determine the footprint of individual modeled units. -Floor area is divided by the number of residential units to determine the floor area of each individual unit. -Individual footprints are determined using this unit floor area and an aspect ratio of 2 (i.e., front/back walls are twice as long as left/right walls). - -A summary of modeling assumptions baked into the baseline mapper is given below. -In the future, updates/improvements could be made to expose these arguments as inputs to the models. -For example, aspect ratio could be either user-defined or determined from the drawn building footprint. -Another example is allowing building orientation to be user-defined, or determining it based on the "front" of the building. - -### Geometry - -#### Aspect Ratio -The aspect ratio of individual units of the building is assumed to be 2. - -#### Foundations -For buildings with a crawlspace foundation, the height of the foundation is assumed to be 3 ft. -For buildings with a basement or ambient foundation, the height of the foundation is assumed to be 8 ft. - -#### Walls -The average height of walls adjacent to living space is 8 ft. - -#### Neighbors -It is assumed that buildings have no neighbors. - -#### Orientation -For Single-Family Detached and Single-Family Attached buildings, 100% of the building units are oriented to the South. -For Low-Rise Multifamily buildings, 50% of the building units are oriented to the South while the other 50% are oriented to the North. - -#### Garages -For Single-Family Detached buildings with garages, the size of the garage depends on the floor area. -The garage is assumed to be a 1-car (12 ft wide) for buildings 2500 ft2 or less, and 2-car (24 ft wide) for buildings greater than 2500 ft2. -The garage is also assumed to protrude from the building 100% (i.e., no portion of it is tucked within the building). - -#### Corridor -For Low-Rise Multifamily buildings, the corridor is assumed to be a "Double Exterior" corridor (i.e., entrances to individual units are from the exterior of the building). - -### Fuel Types - -#### Appliances -The fuel type of the cooking range, oven, and clothes dryer is assumed to match the fuel type of the heating system. - -#### Water Heating -The fuel type of the water heater is assumed to match the fuel type of the heating system. +- [Building Types](building_types.md) lists the supported residential building types, including feature properties, example 3D renderings, and feature snippets. +- [Building Inputs](building_inputs.md) describes various paths for assigning building model input values for GeoJSON features. +- [Building Occupancy](building_occupancy.md) includes information about schedule and calculation types. +- [Other Details](other_details.md) describes modeling notes, GeoJSON schema details, and assumptions related to geometry and fuel types. diff --git a/workflows/residential_workflows/single_family_attached.md b/workflows/residential_workflows/single_family_attached.md deleted file mode 100644 index a710c0b3..00000000 --- a/workflows/residential_workflows/single_family_attached.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -layout: default -title: Single-Family Attached -parent: Residential Workflows -grand_parent: Workflows -nav_order: 2 ---- - -## Single-Family Attached - -Consider the highlighted "Single-Family Attached" building footprint with the following high-level URBANopt™ GeoJSON inputs: - -* 2 stories above ground -* slab foundation -* vented attic -* 4 living units -* no rear units - -![single_family_attached](../../doc_files/single-family-attached-footprint.jpg) - -The number of living units are used to determine the position (i.e., horizontal location) of individual living units contained in the building. -By determining the position of individual units relative the whole building, types and boundary conditions of surfaces (e.g., adiabatic) can be stored in the HPXML. - -Example 3D renderings for a single unit from the building is shown below. -This unit is designated as having a "Right" horizontal location (when viewing from the front). -You can see outside boundary conditions of "Outdoors" on one facade, and "Adiabatic" on the opposite facade. - -![single_family_attached](../../doc_files/single-family-attached-1-1.jpg) -![single_family_attached](../../doc_files/single-family-attached-1-2.jpg) - -Note that the footprint of the modeled unit is always rectangular even though the GeoJSON footprint may not be. See [Other Assumptions](residential_workflows#other-assumptions) for more information. - -For each unit of the building, an HPXML and OSM model is constructed. -These OSM models are merged into a single OSM model, as shown below. - -![single_family_attached](../../doc_files/single-family-attached-2.jpg) - - -### Modeling Notes - -- "Single-Family Attached" home models may be heated only, cooled only, or both heated and cooled. - - Partial Conditioning: heating and cooling may be applied to just a portion of the living space of the home or to the entire living space. Representation of partial conditioning of the living space of a home is accomplished by adding ideal air load system to heat and cool the unconditioned portion of the living area. In this situation, district heating or cooling loads may show up in end uses for the home. - - Undersized Mechanical System: District heating or cooling loads may also show up in end uses when a designed mechanical system cannot meet the load required to maintain thermostat temperatures. An example would be an evaporative cooling system in a hot humid climate. - - For both the partially conditioned and undersized examples, it is possible for reporting or post processing to filter out these unintended district heating and cooling loads. -- It is important to know, that unlike the commercial models that will result in unmet heating or cooling hours, the residential models will not have any unmet heating or cooling hours. To understand how the HVAC system is conditioning for "Single-Family Attached" home models, users should look at district heating and cooling loads. - - -### GeoJSON Schema - -The [URBANopt GeoJSON schema](https://github.com/urbanopt/urbanopt-geojson-gem/blob/develop/lib/urbanopt/geojson/schema/building_properties.json) differentiates between sets of required and optional fields for "Single-Family Attached" residential buildings: - -Required fields: - -| Field | Type | Enums | Notes | -| ----------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| floor_area | number | | Total conditioned floor area. | -| footprint_area | number | | First floor conditioned floor area. | -| number_of_stories_above_ground| integer | | | -| number_of_stories | integer | | Includes foundations. | -| number_of_residential_units | integer | | | -| number_of_bedrooms | integer | | Must be > 0. | -| foundation_type | string | (1) slab
(2) crawlspace - vented
(3) crawlspace - unvented
(4) crawlspace - conditioned
(5) basement - unconditioned
(6) basement - conditioned
(7) ambient | | -| attic_type | string | (1) attic - vented
(2) attic - unvented
(3) attic - conditioned
(4) flat roof | Stories > 1 for conditioned attics. | - -Optional fields: - -| Field | Type | Enums | Notes | -| ----------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| roof_type | string | (1) Gable
(2) Hip | NA when attic type is flat roof. | -| occupancy_calculation_type | string | (1) asset
(2) operational | | -| number_of_occupants | integer | | For operational calculations. | -| system_type | string | (1) electric resistance
(2) furnace
(3) boiler
(4) central air conditioner
(5) room air conditioner
(6) evaporative cooler
(7) air-to-air heat pump
(8) mini-split heat pump
(9) ground-to-air-heat-pump | | -| heating_system_fuel_type | string | (1) electricity
(2) natural gas
(3) fuel oil
(4) propane
(5) wood | | -| template | string | | See [Customizable Template](residential_workflows#customizable-template) | -| hpxml_directory | string | | Relative to xml_building. Most required fields are then optional. | - -An example "Single-Family Attached" building feature snippet is shown below. - - ```json - { - "id": "17", - "name": "Residential 4", - "type": "Building", - "building_type": "Single-Family Attached", - "floor_area": 18320, - "footprint_area": 9160, - "number_of_stories_above_ground": 2, - "number_of_stories": 2, - "number_of_bedrooms": 6, - "foundation_type": "slab", - "attic_type": "attic - vented", - "system_type": "Residential - furnace and room air conditioner", - "heating_system_fuel_type": "fuel oil", - "number_of_residential_units": 4, - "template": "Residential IECC 2015 - Customizable Template Sep 2020" - } - ``` diff --git a/workflows/rnm/rnm.md b/workflows/rnm/rnm.md index bca5de2a..a8de2d7d 100644 --- a/workflows/rnm/rnm.md +++ b/workflows/rnm/rnm.md @@ -3,7 +3,7 @@ layout: default title: RNM parent: Workflows has_children: true -nav_order: 5 +nav_order: 11 --- # URBANopt RNM-US Analysis