From 3044948c6a3120dac00768fd3ef7acf03b3286bd Mon Sep 17 00:00:00 2001 From: kflemin <2205659+kflemin@users.noreply.github.com> Date: Fri, 6 Oct 2023 12:30:19 -0600 Subject: [PATCH 01/37] try without remote_theme --- _config.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/_config.yml b/_config.yml index dd23c0e4..f54bef85 100644 --- a/_config.yml +++ b/_config.yml @@ -1,4 +1,5 @@ -remote_theme: pmarsceill/just-the-docs +theme: just-the-docs +# remote_theme: pmarsceill/just-the-docs color_scheme: uo title: [URBANopt Docs] logo: "/doc_files/URBANopt-Logo-Horizontal-2Color.png" From 207e44596625d4ba1fae55f2015e43b171b7145c Mon Sep 17 00:00:00 2001 From: kflemin <2205659+kflemin@users.noreply.github.com> Date: Fri, 6 Oct 2023 13:14:05 -0600 Subject: [PATCH 02/37] pin just-the-docs --- _config.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_config.yml b/_config.yml index f54bef85..41eed8c5 100644 --- a/_config.yml +++ b/_config.yml @@ -1,5 +1,5 @@ -theme: just-the-docs -# 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" From d99ec4b4e454b7dfd5574392b5933d80462aa222 Mon Sep 17 00:00:00 2001 From: Katherine Fleming <2205659+kflemin@users.noreply.github.com> Date: Mon, 13 Nov 2023 10:31:40 -0700 Subject: [PATCH 03/37] Update known_issues.md --- developer_resources/known_issues.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/developer_resources/known_issues.md b/developer_resources/known_issues.md index 13dfdf50..7b453381 100644 --- a/developer_resources/known_issues.md +++ b/developer_resources/known_issues.md @@ -53,6 +53,13 @@ nav_order: 3 ### 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 yoour project directory, you can also add the following line to the Gemfile *inside your project directory* and re-run your simulation: +``` + gem 'parser 1.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 From 9b9109afce4a3694621ee02ca88bc619293647c6 Mon Sep 17 00:00:00 2001 From: Katherine Fleming <2205659+kflemin@users.noreply.github.com> Date: Mon, 13 Nov 2023 10:33:18 -0700 Subject: [PATCH 04/37] Update known_issues.md --- developer_resources/known_issues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer_resources/known_issues.md b/developer_resources/known_issues.md index 7b453381..9f375896 100644 --- a/developer_resources/known_issues.md +++ b/developer_resources/known_issues.md @@ -57,7 +57,7 @@ nav_order: 3 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 yoour project directory, you can also add the following line to the Gemfile *inside your project directory* and re-run your simulation: ``` - gem 'parser 1.2.2.2' + gem 'parser 3.2.2.2' ``` ### Version 0.9.1 and below From 1707cf7bd48a33abb94601aec397f9cea8267d58 Mon Sep 17 00:00:00 2001 From: Tanushree Date: Mon, 20 Nov 2023 15:20:10 -0700 Subject: [PATCH 05/37] add ghp documentation --- workflows/disco/disco.md | 2 +- workflows/ghp/ghp.md | 105 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 workflows/ghp/ghp.md diff --git a/workflows/disco/disco.md b/workflows/disco/disco.md index 97aeaf0d..351a1b6f 100644 --- a/workflows/disco/disco.md +++ b/workflows/disco/disco.md @@ -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/ghp/ghp.md b/workflows/ghp/ghp.md new file mode 100644 index 00000000..de57c43f --- /dev/null +++ b/workflows/ghp/ghp.md @@ -0,0 +1,105 @@ +--- +layout: default +title: OpenDSS Converter +nav_order: 3 +parent: Workflows +--- + +# Geo Thermal Heat Pump (GHP) Analysis + +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 `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 `-g` flag in the create command: + + ```bash + uo create --project-folder --ghe + ``` + +This will create an URBANopt example project which includes a feature file with a GHP network as shown in the figure below : + + +The Feature File include the footprint area of the GHP that is taken 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 parameter file: + +```bash +uo des_params --sys-param-file --feature --scenario --ghe +``` + +The `ghe_specific_params` 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. + +5. ### Size GHP + +This involves sizing the GHP system, by 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-file --feature --scenario --ghe +``` + +On running this command, a new folder `ghe_dir` is created that stores the results from GHP sizing such as the g-function and the ground loads for the GHP. The system parameter file is also updated with the results of sizing such as the number of boreholes, and length of boreholes. + +5. ### 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-file --feature --des-name +``` + +5. ### Run Modelica Models + +```bash +uo des_run --model +``` + From 2c65c6f63721dfbe581d71f8d09478090774969f Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Wed, 20 Dec 2023 15:09:49 -0700 Subject: [PATCH 06/37] update copyright to include 2024 --- _config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_config.yml b/_config.yml index 41eed8c5..8956cdb5 100644 --- a/_config.yml +++ b/_config.yml @@ -7,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." From 539d6e83ea7bf60b3d664982719a23812222b716 Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Wed, 20 Dec 2023 15:10:45 -0700 Subject: [PATCH 07/37] des installation doc updates --- installation/des_installation.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) 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: From d1dc8eef67e3290b93903951786c7b6d93a545fc Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Wed, 20 Dec 2023 15:11:23 -0700 Subject: [PATCH 08/37] clean up dependency table code, and update python versions in table --- installation/disco.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/installation/disco.md b/installation/disco.md index 11de197f..c7d238ce 100644 --- a/installation/disco.md +++ b/installation/disco.md @@ -27,11 +27,11 @@ 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 | To update these versions, modify the version in the *dependencies.json* From 964ed744fc993219cbc1c54c3c58ae659109e9f7 Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Wed, 20 Dec 2023 15:11:53 -0700 Subject: [PATCH 09/37] point to OS3.7 for correct dependency --- installation/linux.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/installation/linux.md b/installation/linux.md index 0e113a89..32373cc6 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. From 03b7b580909adfeea11d4d0900c1fa46d31b9172 Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Wed, 20 Dec 2023 15:12:37 -0700 Subject: [PATCH 10/37] point to OS3.7 for correct dependency and improve GMT wording --- installation/mac.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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. From 007048f25bb7a4dc50b69434a2094f5b04840e11 Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Wed, 20 Dec 2023 15:13:27 -0700 Subject: [PATCH 11/37] clean up GMT wording in linux page too --- installation/linux.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/installation/linux.md b/installation/linux.md index 32373cc6..d71729e3 100644 --- a/installation/linux.md +++ b/installation/linux.md @@ -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. From 7009cfc262a9f29918c0e06b034b2d9b8ae60f95 Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Wed, 20 Dec 2023 15:14:09 -0700 Subject: [PATCH 12/37] fix OS link, fix a typo, clean up GMT wording --- installation/windows.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) 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. From c53e06c6b3952fcee11e85ea8440ddc1b4122512 Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Wed, 20 Dec 2023 15:21:03 -0700 Subject: [PATCH 13/37] fix typos and clean up outdated text --- developer_resources/developer_resources.md | 30 +++++++++++----------- 1 file changed, 15 insertions(+), 15 deletions(-) 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: From 96ac913aab3656a0473c65481948e0ea084327d9 Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Wed, 20 Dec 2023 15:21:32 -0700 Subject: [PATCH 14/37] WIP: compatibility matrix - still needs uo gems --- developer_resources/compatibility_matrix.md | 28 +++++++++++---------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/developer_resources/compatibility_matrix.md b/developer_resources/compatibility_matrix.md index 5582def2..956db581 100644 --- a/developer_resources/compatibility_matrix.md +++ b/developer_resources/compatibility_matrix.md @@ -9,25 +9,27 @@ 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 | Ruby | Python | REopt API | Modelica Buildings Library | +|:--------------:|:--------:|:----------------:|:----:|:------:|:---------:|:--------------------------:| +| 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.11.0** | 0.11.0 | 3.7 | 2.7.2 | **URBANopt Gems:**

**Python Dependencies:**
DiTTo Reader v0.6.3
GeoJSON Modelica Translator v0.6.0
DISCO v0.4.1
**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 | From f95e3c41879aaf88dc59c55a86a3ca2d5aa5e4c6 Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Wed, 20 Dec 2023 16:44:11 -0700 Subject: [PATCH 15/37] fix typos in known_issues --- developer_resources/known_issues.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/developer_resources/known_issues.md b/developer_resources/known_issues.md index 9f375896..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,7 +46,7 @@ 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 ``` @@ -55,11 +55,11 @@ nav_order: 3 ### 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 yoour project directory, you can also add the following line to the Gemfile *inside your project directory* and re-run your simulation: +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 @@ -67,8 +67,8 @@ To fix the issue, either download URBANopt CLI 0.9.3 and recreate/update your pr ... ``` -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' ``` @@ -88,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). From 916d21d7fb19258f9d2461dfaa0ac2cb7d541690 Mon Sep 17 00:00:00 2001 From: Tanushree Date: Thu, 18 Jan 2024 15:15:31 -0700 Subject: [PATCH 16/37] add image --- doc_files/ghp2.PNG | Bin 0 -> 82482 bytes workflows/ghp/ghp.md | 4 ++-- 2 files changed, 2 insertions(+), 2 deletions(-) create mode 100644 doc_files/ghp2.PNG diff --git a/doc_files/ghp2.PNG b/doc_files/ghp2.PNG new file mode 100644 index 0000000000000000000000000000000000000000..b8c81cd312900932f7a32f8035b14c50fbabf21d GIT binary patch literal 82482 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 QoPdAlw2ib%HLiyLAG+%Bx&QzG literal 0 HcmV?d00001 diff --git a/workflows/ghp/ghp.md b/workflows/ghp/ghp.md index de57c43f..d1ba1072 100644 --- a/workflows/ghp/ghp.md +++ b/workflows/ghp/ghp.md @@ -32,8 +32,9 @@ URBANopt CLI following the steps below: uo create --project-folder --ghe ``` -This will create an URBANopt example project which includes a feature file with a GHP network as shown in the figure below : +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 include the footprint area of the GHP that is taken as an input for GHP sizing. @@ -102,4 +103,3 @@ uo des_create --sys-param-file --feature ``` - From a60c5ae234605c800563d8465b570e3289fa78af Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Fri, 19 Jan 2024 10:37:39 -0700 Subject: [PATCH 17/37] update compatibility matrix with UO gems --- developer_resources/compatibility_matrix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer_resources/compatibility_matrix.md b/developer_resources/compatibility_matrix.md index 956db581..34949495 100644 --- a/developer_resources/compatibility_matrix.md +++ b/developer_resources/compatibility_matrix.md @@ -29,7 +29,7 @@ URBANopt™ depends on various other components to function. Ensu |URBANopt Version|URBANopt CLI|OpenStudio|Ruby |Gems | |:--------------:|:----------:|:--------:|:-----:|:------------------------------------| -|**0.11.0** | 0.11.0 | 3.7 | 2.7.2 | **URBANopt Gems:**

**Python Dependencies:**
DiTTo Reader v0.6.3
GeoJSON Modelica Translator v0.6.0
DISCO v0.4.1
**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
**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 | From dc25d080cd4bf7713f4c202c86f1c6692c7592ce Mon Sep 17 00:00:00 2001 From: kflemin <2205659+kflemin@users.noreply.github.com> Date: Wed, 24 Jan 2024 13:49:11 -0700 Subject: [PATCH 18/37] update ordering and formatting --- workflows/carbon_emissions.md | 2 +- workflows/des.md | 2 +- workflows/disco/disco.md | 2 +- workflows/geometry_workflows.md | 2 +- workflows/ghp/ghp.md | 65 +++++++++---------- workflows/opendss/opendss.md | 2 +- workflows/optimization.md | 2 +- workflows/photovoltaic.md | 2 +- workflows/reopt/reopt.md | 2 +- .../residential_workflows.md | 2 +- workflows/rnm/rnm.md | 2 +- 11 files changed, 42 insertions(+), 43 deletions(-) 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..81e54514 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) diff --git a/workflows/disco/disco.md b/workflows/disco/disco.md index 351a1b6f..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 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 index d1ba1072..e251bc93 100644 --- a/workflows/ghp/ghp.md +++ b/workflows/ghp/ghp.md @@ -1,11 +1,11 @@ --- layout: default -title: OpenDSS Converter -nav_order: 3 +title: Geothermal Heat Pump (GHP) +nav_order: 5 parent: Workflows --- -# Geo Thermal Heat Pump (GHP) Analysis +# Geothermal Heat Pump (GHP) Analysis 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. @@ -20,28 +20,27 @@ uo install_python ## Usage -In order to use the URBANopt-GHP capabilities, the `GHP Project` can be created and run using the -URBANopt CLI following the steps below: +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 `-g` flag in the create command: + 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 : + 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) + ![ghp2](../../doc_files/ghp2.PNG) -The Feature File include the footprint area of the GHP that is taken as an input for GHP sizing. + 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. + Scenario files are created next using the following command: ```bash uo create --scenario-file @@ -65,41 +64,41 @@ The Feature File include the footprint area of the GHP that is taken as an input 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. + 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 parameter file: + The following command can be used to create the system parameters file: -```bash -uo des_params --sys-param-file --feature --scenario --ghe -``` + ```bash + uo des_params --sys-param-file --feature --scenario --ghe + ``` -The `ghe_specific_params` 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. + 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. -5. ### Size GHP +6. ### Size GHP -This involves sizing the GHP system, by calculating properties such as number of boreholes, length of boreholes and the g-function. + 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: + This is done using the following command: -```bash -uo ghe_size --sys-param-file --feature --scenario --ghe -``` + ```bash + uo ghe_size --sys-param-file --feature --scenario --ghe + ``` -On running this command, a new folder `ghe_dir` is created that stores the results from GHP sizing such as the g-function and the ground loads for the GHP. The system parameter file is also updated with the results of sizing such as the number of boreholes, and length of boreholes. + 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. -5. ### Create Modelica Model and Modelica Directory +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. + 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: + The following command is used: -```bash -uo des_create --sys-param-file --feature --des-name -``` + ```bash + uo des_create --sys-param-file --feature --des-name + ``` -5. ### Run Modelica Models +8. ### Run Modelica Models -```bash -uo des_run --model -``` + ```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/residential_workflows.md b/workflows/residential_workflows/residential_workflows.md index 1f721fd9..212780bc 100644 --- a/workflows/residential_workflows/residential_workflows.md +++ b/workflows/residential_workflows/residential_workflows.md @@ -3,7 +3,7 @@ layout: default title: Residential Workflows parent: Workflows has_children: true -nav_order: 7 +nav_order: 10 has_toc: false --- 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 From 37a3f70c48a52b3df218e4f7dcbc70c4e4ab989b Mon Sep 17 00:00:00 2001 From: kflemin <2205659+kflemin@users.noreply.github.com> Date: Wed, 24 Jan 2024 13:52:20 -0700 Subject: [PATCH 19/37] add uo min version for ghp workflow --- workflows/ghp/ghp.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/workflows/ghp/ghp.md b/workflows/ghp/ghp.md index e251bc93..a5bd7369 100644 --- a/workflows/ghp/ghp.md +++ b/workflows/ghp/ghp.md @@ -7,6 +7,8 @@ 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 From ae0925d2465a18ad2f64a9cf0d4e5fdec27a8901 Mon Sep 17 00:00:00 2001 From: kflemin <2205659+kflemin@users.noreply.github.com> Date: Wed, 24 Jan 2024 13:58:37 -0700 Subject: [PATCH 20/37] add missing python dep --- developer_resources/compatibility_matrix.md | 2 +- installation/disco.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/developer_resources/compatibility_matrix.md b/developer_resources/compatibility_matrix.md index 34949495..c9440071 100644 --- a/developer_resources/compatibility_matrix.md +++ b/developer_resources/compatibility_matrix.md @@ -29,7 +29,7 @@ URBANopt™ depends on various other components to function. Ensu |URBANopt Version|URBANopt CLI|OpenStudio|Ruby |Gems | |:--------------:|:----------:|:--------:|:-----:|:------------------------------------| -|**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
**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.3 **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/installation/disco.md b/installation/disco.md index c7d238ce..e56d81e2 100644 --- a/installation/disco.md +++ b/installation/disco.md @@ -32,6 +32,7 @@ This installs to the following versions of the python packages: | 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* From ad29d9a183b3c7596abf66820281eeb6948e09cc Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Wed, 6 Mar 2024 10:40:09 -0700 Subject: [PATCH 21/37] fix typos in ghp workflow docs --- workflows/ghp/ghp.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/workflows/ghp/ghp.md b/workflows/ghp/ghp.md index a5bd7369..9680c330 100644 --- a/workflows/ghp/ghp.md +++ b/workflows/ghp/ghp.md @@ -84,7 +84,7 @@ In order to use the URBANopt-GHP capabilities, the example `GHP Project` can be ```bash - uo ghe_size --sys-param-file --feature --scenario --ghe + 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. @@ -96,7 +96,7 @@ In order to use the URBANopt-GHP capabilities, the example `GHP Project` can be The following command is used: ```bash - uo des_create --sys-param-file --feature --des-name + uo des_create --sys-param --feature --des-name ``` 8. ### Run Modelica Models From 158396a83139910a537dafae05633ce6426dc067 Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Wed, 6 Mar 2024 14:15:40 -0700 Subject: [PATCH 22/37] Refactor residential workflow md files to preferred structure. --- _site/index.html | 2 +- workflows/residential_workflows/arguments.md | 98 ++++++ .../residential_workflows/building_types.md | 295 ++++++++++++++++++ .../residential_workflows/customization.md | 47 --- .../residential_workflows/multifamily.md | 102 ------ workflows/residential_workflows/occupancy.md | 40 +++ .../other_assumptions.md | 56 ++++ .../residential_workflows.md | 148 +-------- .../single_family_attached.md | 97 ------ .../single_family_detached.md | 93 ------ 10 files changed, 496 insertions(+), 482 deletions(-) create mode 100644 workflows/residential_workflows/arguments.md create mode 100644 workflows/residential_workflows/building_types.md delete mode 100644 workflows/residential_workflows/customization.md delete mode 100644 workflows/residential_workflows/multifamily.md create mode 100644 workflows/residential_workflows/occupancy.md create mode 100644 workflows/residential_workflows/other_assumptions.md delete mode 100644 workflows/residential_workflows/single_family_attached.md delete mode 100644 workflows/residential_workflows/single_family_detached.md diff --git a/_site/index.html b/_site/index.html index 5d1e5e7d..700a7b83 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/workflows/residential_workflows/arguments.md b/workflows/residential_workflows/arguments.md new file mode 100644 index 00000000..c1b8289d --- /dev/null +++ b/workflows/residential_workflows/arguments.md @@ -0,0 +1,98 @@ +--- +layout: default +title: Arguments +parent: Residential Workflows +grand_parent: Workflows +nav_order: 2 +--- + +## Arguments + +- [OpenStudio-HPXML Defaults](#openstudio-hpxml-defaults) +- [Customizable Template](#customizable-template) +- [ResStock Samples](#resstock-samples) + +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): + +* 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 + +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. + +### OpenStudio-HPXML Defaults + +### 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 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 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. + +### ResStock Samples + +TODO. diff --git a/workflows/residential_workflows/building_types.md b/workflows/residential_workflows/building_types.md new file mode 100644 index 00000000..c574a43a --- /dev/null +++ b/workflows/residential_workflows/building_types.md @@ -0,0 +1,295 @@ +--- +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* 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). + +### 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 [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) + + +#### 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. + - 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. + + +#### 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: + +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_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 | | +| 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" + } + ``` + +### 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" + } + ``` + +### 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/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/occupancy.md b/workflows/residential_workflows/occupancy.md new file mode 100644 index 00000000..7eb51636 --- /dev/null +++ b/workflows/residential_workflows/occupancy.md @@ -0,0 +1,40 @@ +--- +layout: default +title: Occupancy +parent: Residential Workflows +grand_parent: Workflows +nav_order: 3 +--- + +## Occupancy + +- [Schedules](#schedules) +- [Calculation Type](#calculation-type) + +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. \ No newline at end of file diff --git a/workflows/residential_workflows/other_assumptions.md b/workflows/residential_workflows/other_assumptions.md new file mode 100644 index 00000000..ce6f49d3 --- /dev/null +++ b/workflows/residential_workflows/other_assumptions.md @@ -0,0 +1,56 @@ +--- +layout: default +title: Other Assumptions +parent: Residential Workflows +grand_parent: Workflows +nav_order: 4 +--- + +## Other Assumptions + +- [Geometry](#geometry) +- [Fuel Types](#fuel-types) + +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. \ No newline at end of file diff --git a/workflows/residential_workflows/residential_workflows.md b/workflows/residential_workflows/residential_workflows.md index 212780bc..5bdaa0d4 100644 --- a/workflows/residential_workflows/residential_workflows.md +++ b/workflows/residential_workflows/residential_workflows.md @@ -12,148 +12,12 @@ has_toc: false 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): -* 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 - -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 building types and details for each. +- [Arguments](arguments.md) describes various paths for assignment argument values to GeoJSON features. +- [Occupancy](occupancy.md) includes information about schedule and calculation types. +- [Other Assumptions](other_assumptions.md) describes modeling assumptions for 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/residential_workflows/single_family_detached.md b/workflows/residential_workflows/single_family_detached.md deleted file mode 100644 index a24f148d..00000000 --- a/workflows/residential_workflows/single_family_detached.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -layout: default -title: Single-Family Detached -parent: Residential Workflows -grand_parent: Workflows -nav_order: 1 ---- - -## 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 [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) - - -### 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. - - 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. - - -### 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: - -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_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 | | -| 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" - } - ``` From 99d5f3cc93e1bbce91dbb1dede05f3efbe88edd3 Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Thu, 7 Mar 2024 12:17:33 -0700 Subject: [PATCH 23/37] Bunch of updates. --- _site/index.html | 2 +- doc_files/os-hpxml-resstock-workflow.png | Bin 0 -> 62182 bytes workflows/residential_workflows/arguments.md | 98 -------------- .../residential_workflows/building_inputs.md | 121 ++++++++++++++++++ .../{occupancy.md => building_occupancy.md} | 16 +-- .../residential_workflows/building_types.md | 29 +++-- .../other_assumptions.md | 2 + .../residential_workflows.md | 15 ++- 8 files changed, 157 insertions(+), 126 deletions(-) create mode 100644 doc_files/os-hpxml-resstock-workflow.png delete mode 100644 workflows/residential_workflows/arguments.md create mode 100644 workflows/residential_workflows/building_inputs.md rename workflows/residential_workflows/{occupancy.md => building_occupancy.md} (83%) diff --git a/_site/index.html b/_site/index.html index 700a7b83..5f7a38ea 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-2024, 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/doc_files/os-hpxml-resstock-workflow.png b/doc_files/os-hpxml-resstock-workflow.png new file mode 100644 index 0000000000000000000000000000000000000000..7887c0c3c2b874b8f9b49f73ebc8999114204f8b GIT binary patch literal 62182 zcmcfoXIGQk7c~xph#*MGLArpzQB(v(0w`SwMG+9Bw}_~OmPqfQ)KCJJBPd7<9i&MK zh7yscA|-?#NCXr@3m_ptLc%}i{OWL#rkd9$xQ)?RC_Ip<2fXKBjEBf-PQ z#>RKs3}nN`#(`yHV^8Bg#d^cL`~}K-um{m zero0v#Ky+o^Y4#+09N^kjqOj=ZO|>-aQBTE&LX$I7LAy#mJy;aeZQ01QdVZ1W)y!i z1*!DczTn(^f`Y*dwg67U7lJ1O!ouVY4PD6=(7Ac1rrU&S-n%bpR^)__r{i5^n#$ z4`Y4bZ4TrC2`eA`>#K)W;K7T9TUya1HYuHkLMnOQ+@*D^bT1EuYt3)>K4vmB&b-_H znUy`z8xkQnt%t3=dfWKq|8o+?Y#I0T0u%YAw9L3NZV*sm0-H0PuR}M1i{W^U*#>X5 zTGyt6WhEC2&y}ks(n~A%>FjDG1XPGrm1Q#4vzdZz$~VPn6D`ZLQihA!aoMBI#=ell zS*2!gy7Fv0Oke6r0AmUJFuRZ3Vg<~;EFfi>(bbmBC14zGHj0k;a`DdpyPGtf0c?pW z!c5PgJ#0&3FZ=~xw~1R z=Wf@B<{K!{hl-${qN9~JYe;lE$x6sB|7>GaJs^r}GgF-*Hq+UvO-R1vtJVAO2b@M+ z(+mG~>DI^iloDX=gKq;rWpQV?1Y|DDmdm~pkkROZXlg~C%aXv@CN;~Q5XS!B05q27 z(Ei@^WVlouSAqR?`!(d}HkM+&&pu9BDxgHKlPTMDFgD);Q#y;l6jj&9TB5rCaL&_w z9MGG4^;K(<#Cv594g*>T`@MhBUJhH=YuOG{TGuNV#dA$7NrO^Ov&b; z!)VuhR2t{LtbEu0hQ66^>sA?Hu+;{&rD-!2A$e85u&Dq&LNwF&o3_xVN}Js_QC|z_&;8&n zG`5k~E_Tzrdh(ZV_0F=UZIib^^wdzm(~ZOQgp5jQNMCSE8126Q zE}co0uk_CH9*_EdJ-0njzIMJDA)@4B9Fv@(9_KJtpc`cg>m8f>YjcU&Nr!A@ z<~K(zU7Y>+RJB%GBVMF+-Jl5^izwHp{cZ7SgBrv&_i#$XR-_q;#eWY%F7o7->- z_K&u%I-Ao&H_Lmp3n(cSUd1JfOLP>U}7{F*33h|z6&b*NS+>+>m_|D~C) zd=G+77zQ7Hd^}z|Vo-f(qgcHksU5kIpiF`0xKk#cy#xj>+Dd4Ki10~h=IgC$7q}lj z5}aqmTFDo+-~Zh|U-ey*XtP(|Svjd4Q<*uRq~~rhwJS(&A!nA_TYF%2V@gqzA z(|_|6LjGw+-ImcZG!@7*E?&q=HvO?voY1CAYXFp)lD>M(DNF5eWaWDH-u$K09z9Cd zlWEZ&owg$$%==E@H1J zG~yW1$vTxE#?IGya9tu`F9f*PZ3;P@B91co)~g^R9<)Dn3)`L75flN7ic$Se-8Zp5 z;fAkoQ)-sgAU55hO?A39NS)OGvb(YK^O}VF6_zc?!>qU?`TVC}P6r$c9B&H*58qrF zHCO2b4gM$^=9WHRVwGY5l81{=eIPtm%D^aZ9{&`dsm+|z>4`hkH2ptS;H&Prn}NNA z?~I;!&he<9g4M^)F4fS)U_=hy2H}9ezuBKpsteOES<#}D+UuI!!vv^7mXG=;elhIZ^4kKk) zUy;#YA?6Tj|C{CqgFZCE!P3^BO-aZ+d9&H~xC`E(F*qon%*B7MR4S>)d%pKu^Tr?) zSc4q|Qd@mYt~wMEFnTW|j~1uK*W=<$JL7`n_LvxbG3HC!5&7@6UAn&Y7LloHxRi2D zH||hU;%Wa)V6i2K^A2_Z=>H?wM=MmAQ9KkDY`Ang_>1Ig#50ZPpzHZq4~-#k)=;%f z=U#^CfA_EWSy*b>X#UNhi}S%a3rg1UL6&>td+xZyL9os1ix!ae$yyDIV`#ALkqPJZ z!6nb)=!Z8XrfIk3l!QnBR}lhb1PdKKhw?OYPMr}q2?Kh=K*7G%3?J?4-AL2w{eDy1 zts$#Qcic!NQyYA*XCG6}g{L4LFk&V$0`Km~V_fd?@=jvEhnU#bIht}*sFYQLt8iO7Qx zbm>}8un1^3#N-)h_TiDZ?OH_=DU)iA{?<#EP{C&49}UF#M~T{3qIub#62E9IMkuZml_@}NcewH3n1Y*x9I;& zCWZoFY~hvg-5>> z`Y9mgc%1I`gIT#ZPID)WpjI zm+F82mo4R{y0x*yxMN*DNxfHO*eo`UN)2Po>PSl0|e$v`QY6BxY79m#mDnadI|4WY{~SLPV9^o8BbHpwiG8t_GgVqS!xtfN@JITqy-CC;PZNPVM~J%5mu7#U{$L*a5wU+zHdWBlEDU3prU4s3i+HbdXYK419zgIJss(G^c zv`}q4BkCxBX*F||=R4u3i}LF&|4f)tk|e=(Of zUm2Iagr!xiMlxYdH%U(t_3X(9N7%~#t&)p4URYSsmHp1UqVv=Tr?F=|HbjT`OSG|V zWs)N%^G7-(ec&&B)C-ZVNpVhx3VP71^yDU6uS8{Cu3=e;^sh8+d*iYk}FFpO++ z=f1noXc7BFJ-E<4ddFBoFS<=!aLUx^rT7n1?Bg6ad%4ayIx4P21#>h;3+giXl|Lu= z&;)2GxRe(k{JD*+7Pph3#-@3su{e8R9Gd_r7N6yw|qKbDv&|C^>^X2QtgN z^1@D^#fEhq3(w<@B+;nHRk4GE+Tq%dAjoj~i*ys?k4}UQ+A}y_-W; zq^p^qYl7D%_(&U)LV`p6$F4&BI$P!K=56w1@hSCEF8Am{4L>*>(vhL@VJ|^ZY)4M@ z>DF@&Ds`iV3v)|<)h3H9O-x;ex%>D0yy*q^qa&}SJRN8nH?`QI`V&lilh0J_>`Bq~T>!Cp;j>WNjz_W}QXYC(s#{2lnai_5!TXk;`IjlvZL$+b^)9dKA33B~N>@KBB> z_DH`J(Bka6>T*bMA!s7- z>*4LEQC5v|z_B+OM=Sa&0LwokaZI&|O6wjTe>Rxw2fG^kRG0Rb$_1!Xegusuc@f#n z&DQJK?0L!6rROqZQJn=90<^9>GSt}o-2K>z?Kj*}op+QX)r-4>y2_06R_=9YmYG1e zfUD;;j`<~|KfXf$Dthk(P+~8hskT$3XWX0>?AYm-T%B+Lx2S+$w~t;@yZ>dy-u`o* zK^z@VoZY<%89l#V&g!AR>TT#WXO%n3WMekf3#wHWOhb^ro{N~zT#vUwiX$!=Y zlWddZ?mi&&IrHX8Ee&LqIkwdCm*OqGWg2U!oVZ|Y@%SR{s%IjFTW_{edxh=w6B4pm; z!jj3&&u~(`)y+Ht`j>{*%EB-UYF->YZBa3X>D0`Z7Vmh^gW6Pktmh}<{vQk8<^5(0e@-Lz2+8;%R|L))^T6!_!1s%-u`J z193+wG4`~d-Ct{oTbSe6RF~czr>j?i8%3!BxT7R^rp{@LW}lVo=z2FhbZy^ZuuBbZ zRp4NHRobCTnVs=qb**yInvx3ASxKd2R;jK$N}FI(OVcRktntdVrM|W0AH~WD;9a`p z;kq~Qa-difK*&wy++c2z-<6`E3nErAbZS}Ch+caeSs6-&dEFwlAmXA1w&99vLN{NkyBi)!w`Gkqg&)wSu@G_sUZI;9S1iug4M}L!slQ zFRwh^`DB@|Wn1sA8&x54GT!i|@&iIkVViT;`-_%u4PYThY1JA&mqEb_^11qDdD5{7 z!=Jj?^8-TswN{ext2DZMNt83SG)0RacP_Ggz3p(%fgk_!3#ou;rmT? z7r6C%7K+Ej2L%6qAf(Y*hxLeKijzkT>6_3f)Xp(ak_x7e(%ai~6XNwCz}>3yi5 zqks5K-#Aq>T=J!#@t&%xTayW2RJvy3LV|#v7(!?#?(lbxzcc^@U3p@Sj$E;c{JHeq zw$|Uc8oMA@O<4G=dUoMq^<<;m#Ku$E2}qdigkPNOgiqY_fEv&Q{@pc`M?~zOE#MQ6 zxYv_rvk4 zTT6k{G+Da>wx_{=qnk2ZW{>y4#}kvHDh^R=RTY)iB_`PiZdEpAi>+T2dU<$w?re}^ z|9n%J+(NI{DH4XB$=sK2f5H6r*Ff0-aonx^rM_xBe+i{ z1`ZO0x5@Q|GJDpgJUZmy0jaQ2x3KxgRdUWREg!h|z3=duxRR^mEf=%xy$^@S_Q6S0 zvv|>TyQnVC{1|^Xt)*&bd(hI>s>67Z;+n2MY&~|G3=$|d)sxQt2=C{o2=5hYdh?Z4 zpe>6OFk)6#aq2ItG1G*!bx%1ORI3M0;s;ZULwwUAzrVj}J@Tj(h(-cV&`8B4z=-*W zKETernBr-Lbd$XPp8V`?Ioi(!d3ysG*y({jSpDaZT{**j5awAw83-jx2W%pm8{AB1 z(U3;QnaNx7MUC1WBiwkVIm$Zkv?6I2W@0_!9A=Hd4Qm9LlOaZ+Fx^d^$iq891=94f zSOSk6ZNK)3b!|a<s)l+b@cd`~)*~{x98p|H)qC zk8kZW&NF;zxk1Df z+Se@zgTQ=3DbtmFVGdsOO^(y8v6F_9e{CwLo>1R*&Arlz-aavg9E=*XRu^ zP5}q-DKU=BXIuRu{^o0pFVT1g*1nZJZCi} z!O@*(|D~==Pl{-U=TTQH3f-^zHL9g``{BwhsM)@4`5}`|!3#;EHhpQr=@H$WqN6ug z-WwhN8PQjZf7eG*wMMw0oLqZ0Su|JkVWyaBJoB*dcn1AkK>z3|=)o;GGyF$GEu2}( zV+RXk^@YC6&Pvzx0!txoDJ8z@JghB-d{U=9-8BI(EB&kEB;yN^PGm_ zd}!C<^3vkM+dd8Y;nG$?>oUMl{;dP$j-L?B;;EV@dZL>zUTeZWs7;jPZM*=Rm-%fpXV|~rKQ?p&H zTl?x2WD3qR9|6}mp=Ax=dl}8(fQ{YCupM^VsS^n;o5cCe`IsLV9v%9rs^nSazO(WusMqviDiD5 zT-gT90==XyVo25!!Gt8L(p=romc#~)bFK?=xqCw2MA*neWOMhqVpQG&dfxeWb z56zN|mu1uRbA)keof$h1#TMKQI+cGwCkhWB5;cF#LmK4~sK8y`%54)Ef0oPJ9sApC zBiGdKz#;M(zRj3tKCS3P=gjE*i?!!WgdEOPoE}WESy3ITyfx@s^#pHTg$B$_XuCfE z?e*EBhWMHxQts}jioM6wC;Eh@IJI*|E9717l|c8gYDB{Akx-bKN@#nIGX-Y2d-s6D z6!D@D+617Oo-b;A?Y}4ud>G9{i;pAseJOvY_V1U}Zx!cseadk^qOnIddC5y$M=AKv z-iHKU+sSyqwSDf!TKJIq)U@a2^JSxyPbC)i_3jod8VTk7GZgAtYm8sg`QU;YCJ>au zBE`8mtcO7dAh2Ho@1?euJN>5a$`4Z^&*-Ax;{%uY-a~H+^BB(%{t zyw}U`BFz-~boqfOg8+crQlEV=nJ-)fEn*kD9D}C!kb|w#VXMRY?O0+GBAlq<7HQo16F*v6pAMe>5*3F(aMdN<9)O z)8CqYM0#@8y0vHXix-QExOQKP82>QRx;bx=!0UxeSHqO&JPEC^)7Fr}NJ_`_SquBK`n<4oZMXfad4KsF{k$+m(x6=viga7o9Gxs1%-}9GUmvh2N}7)x zZEzr#X~flA`CDS%(vBBKvajdIV%=8t;&k4)ccA$hzjx{=P5n!xL{x<-DEO)bJ40p5 zvc#obrBs?%V&w<; z+(CBu0@z}{=pml!if*yste#v8jBGHnkT`NvnHxoXv8GcuH;hlhE#S8e(%kj9$lxNU zrYE5TOfd5|*iQnYpi`6S=C9+4XlG~Z_2^F9rH+}aU}3Sld4FwYqNn6x$+V;>PV*xJ#i|2-_|o zQ)CyVfukDHkt#kqPnPt4?#ACeol(Y>C0+iwU2~M0&`9h}Pmc|c=8QXh=yCPwjZB4Z z&$_%*bJsF&h5uai`0(evvh+x|SbAUVhlXb?QmOoTY-&!+aPH05U7MQlwT{_jpN_fN zG}0B58-;sQXcIG{Wr$=LQadlkI4ovceSQipY8O$*neW}Z_em27M55d0Q?pUQ`ey+1 zVG{l`fU8K^43!T@*K|i?&+G0SI?`R6g}-0;BGvvzvVBsN5UFobs9Tt=|9u|3p9 z;s7KsqyoUlZJ+m_ZF(JfweSvXWYxUW{%(mdUUT$ik7-tt`a%P5XUyRp=kW#kc3!t5 z4XAA7yA92*CvLe6A5R){a~}d-()6ATQWj`d^%ry7@^{1A)>(J!}x%aCx>_G$S+F7Uk|n>l=ylz|lvJkF4mIIp#tWbNm9jSncLNLsMxa z(rm9V_Kmiift`yzlBuSTVp317k&uul-H!6{iq4-sT1`EPwqB1~;gX{{U}$gV5y_HFLePk=#<_|lxAk;o^w;I2Z3l2n3!_;K zqzbw^w-evSQr4!!-wPaXvbad$4epc5Io)k*DpBPJTa{tEnyGvKJ3OJ)=g!&tBYYn^U?Ixvd5 zaeJ#{H*<(%`H#{eAS$=Uje{I=K`=)E2h%_G`aL zJr-PfBq3OQ@Xzwb4AHvqxltw4*93$a|DHzrZlzhGR$pZy4C_o;!_2&s=-MxvPs-dd ziDSL`lwyhbc*-ue{8Q%}7qW@IUoQo30)n;5(L&^rTfw~nk3?x7wX95`#~M4zb<8&5 zLBR1>|G5rczOW4&usZ{gi-BBLa{Ab-r}y?UfKOU0d^%P%aq|$LVLVh21>}a^1{lNB&KNQ3@g?(2loHJYELTXaW`1yF61i6SMVWsjRBF+6;fz z?>`5-TP`GF#k1@yw5pGQLxF*BVxso3@>h^cw~U+R9vg%=3ZB5DU@%es0fHF9rIB^Z zLObB@t>?7IY9K?iAPohFDrVc-GdGG%3U$vN zmSzKp>au7Tuwje-k>bSRPoL_YF2Ju^1RKomrL-^jO|M3!i}tnS=L&MyKUY*$B>J1I7jItr+oeg#6;PWwps5eHVo}%a4XP$CI%jM#FGh$d5c5$RTM(J>ANOo?O5{Sci+X`mfqq<e}c?Qy?<(oQ<}#+w=*@9y{{+ttPNRZ+}A(uKsopK+S}oh9_4C=;$m_;%Eo2(R-_ zgbh(e#TO!P?iKDO?V&snB)vOaB)s@$Rews3(@S5@Kst{tJz)?M+WoiC@}(H{Pr7!n z09iZ#ICi@}Xh9C$$lv8r&f(2{R8CS&mvuf4ydb&vb~91J$ybs_D(thIoaOH&^|0d&K8 zg^%Jj1YzsYvC`8@uH20=XRcn~$?3ba-6sm34j06Zxh=B#l-BkU3}X|vd6U9Ea>3|< zywV1m%}ij^{ZruMb^h*=_G`-Jci-83u}Xt<?oGPDTFBGt1OCozQ|3v{hSpu5 z(w@f`UhnD|nQ0Uabj+5K!yv!+^*M~8r)}5i%bMmFKaM=cM!PM)_8=ilG zC~8gZ?VZMb`SNqRpVkO1HQj4ISW+BRyJM_l_Vy6fcO;Q>T>{+||P=LX^E zkcewokS8(Ar7CCBU&4$%6=)x7*2MrZ`V&#RLTE<*2m(&_fvt9-?5xmxRr{Nkl%zLX zEJ~kJoTAOAY8Y85JSHHnv8kJ+;g7%FavoW)DJSveZP;5rS!4jOru!x8ubidT=b;>{ z%L=*J3+e?8D5#9kC;$+%+=9CQCQ1TZ9Y0|YDw*@B(znuUEX_z-$i>X%bExFDhwp_+tCh2Tb7FR#t4|{34|k5FYG<^t zl3VMm{!DSJo|Mc6m7-j=u(~11FN&|2RwVu7U5v%S>nR*GgxvJ}&&cPGiV%#)(#=znD_2uv{5rb5f5xF&J9!l{ZYCP((0PsQ#0 zqg2)X7@E0F(2ql0mu4}E()16>!c&5ac6j?z1-&|BZGI@SOmcZlck|f94lfRvpDZPk zAEGOEm4IGLH?+(E))CLB*jIeKkbOWCH)tn7@*s=rhn&jw%Rl?v9gBASC(g$jbu1d5 z0zZFT{0+k%&E#1K@NGFWAjB_{8Xl$frQyaCRsOF)?O@UaVs7TjKRa>)Y($RZRjW9k z!lq?SxVfszlKDX>60r5otDq5j@JKXK`}`7pjHUBG<`TgQHVcjke%`m(@+)*Bg#9Xt z`LwuDVp{oNa5>bsgu6m>pw3bp|Pp{PQ!1;14LorI--X$ORvJaJ(15;w2S+}z2!m0*&pZuyMz!U zE{siV7~(}&lcT}XzIdF!!Jf4L-J~QzZ2IOh-**|2XrwA!a4cN!>2kj?@WI5@rn)&$ zyT|U6suNX*j3}8ggJ?-w>3z>FWg{JK!7~Wm=+7f3+;8C(jNvn^A&5=(I?&M-( zb1oBa%{KdDa$G`X8kh&oZ|b}5{-3+!RZpQ;6r@WA z3S-|FL@$cx>Pf-wx%z{GJrV`6H92E1K6R41THma8iJ)xitH3ycnjCT2&Ukw<)y{`~ za`MeN*g*MGo^*R$Zu|sQqdmk$4#hV7R-E52Dba}?^+H*QuD3QS3}t?l77@spIDFFs)h4G`a>)#X`KKnhQdXl3do%~xh?q8I|$q3fTb({c0resBhr85-1L`qX;7D6C*GzntaqV2 z&POZqM})mj~`FJ)brg=r;6-I2)RfWcU@SEI&)CXvGted zz9{P662GWUMTX}KSa+zbF%YD3QmG(_%D#2NV<8>GvimFtcwT-MK$-C>YTr|3?sXp?#;674PhjU$5lG-LZ3rSgM1e7878<+bi>Me9czTY<)-(OD$F+AiCNk z!m8;eURoU*SO(YzV$y=^$>cd2EqZUu=YK>LXH z5c*p1S-(TXE=hv$1<*Yj;P2e6mY=t7%qplx5?lg2Z@MH1hC6qH$8!y`V#;{L7qGTuN+a_!J?S+7;8p!WIkDL8||CQ^o zt-JUB58vKf+T|ft-l{T1(Y#=J)IRlSd0P44m^pGhS{+XcLQ{_i(jglld`{%8OQ?F# z#H=0g&>cFrZK#^~{A=gi>bUUBArcJsO|6c3!ggmg{zUZ@`AT&%Dhid=apr?1UU9Y9 zsv27&Gf_OCHBp?RUv-;L`=^@IHs*y7>Qmwxsx!OGMeTX!TaRYOXjoOC`5ccsR!`fF z1BltlU(2nnFEQ1tvq)HuwV=mkM6Vp0HoefH$%mR}f}eRbCTT(zv&nwlmZ{Dnz_BZ;BnFxr_5!ag1^6%W;Y&V3&R8BH1@1Pxa~>la zt8SV!w|39X6YZEbgv3K}LopSO9;NA{t7_1C_hyJSF!;6^fN#-KyzOul1q0{lC90gf zo*DC5EE8xgy^)FX$5Y!xGphdW*57*V7nr+I11h zCR5>!Ey7qn0{O2Q1hYtTBCaM~c-qU=3CB&=pgc%Q%t^$_gb**xjo9>6;h zy=|wpj%FE_0J1R|;gb7(6EbSvp-m$!+$Ql*f{5s1GA{;GLr^a4F_{2dg_~PW0cNLwtokhJ#N=Wgp7nj-CoGZW4R{wZ82vIpOay+2;&$~7|$@U)y*_2nq zZk12B@3Cy?aC_DmfwBC+J?z_nX6PT=S(c}F_D_!?y?-m;*w=f1S*bZ}MVam>)%B|L z;XWYJYfX!0k^YW)(~Evx6;5)vI7UP>41y-fNL{+XtZ1@qW>#C0Ht8nhf1?qXJ-?I& zQ0kAV_4WrxgZjs67ViaTbg#NLWo8SXoz{F>-wT$1FI$?kaQNoUp!YFxJm@igscjy8X|5>=DuMfv+@l<{+jpVo z4gispJg?d!OB4V8B)2l zkOn#8KjHp&GSCUMl$3t!v$DE=&HTs5gNr+v|EfaX4+@O+dj?$?6fBNG=)6ILf>D-ar0L~D*kLQC|U+Od1YqwzEn4gs$_`jJ90pff23?XmV|MA-DN zynyB>jEmJfpB0140X=O>+J^E)?*zw8{`T~u{fQj0`R(O`Ey*_>!-2)w55D4qsV#gT zp6RX7l7naMLP$f|`J0-^08Od?li`JAdlljobHk8cm?LzjI$ojRU3h=Q^kWCymsY6{ zH%u(ff4=Z?G9Y95Id4)sYO^Rc$YHcZcX z4m0uabn3SX>8PMkyuH!~`YZKxZ`xQY(0BE0ZmZvQ3$SX^6XpCn`X3zc)?~nyuQ(br z$|V5)i9zbzxJ=L^XpXAtvp|ZnEHu{?Jg<`n<0#Y3}og% zd3N*8)G?!cF&YMY+CH>T$`bQ=MoRBvwd3(Ft=jHpA+zqre0W!@5WMT%i5-nie&LMc z2-`BoA!R#9-5ZBJA;h@G2><&}ag{J$)Fz+mU>zbKUW3wH6hkGU+W%Q=!Ms{SVUpKc z>53E3xZ20_p;Nin!KQpJU@H^~omzfX<}sJiQ~L8E%4V-+a9sO$+s?i>wk;MHUh^j& z9k#mKX}KEM>9xJ+0(!ite=p!@c71++=B2!;2u4a$TbYf{wF%mV6~eP0=5?<&!ux}s zvq6{o1H3^jt3*F|E_;|***_T0=46#*Xw7_j7lgShdL|0db@|d^pmOS$P7_d843T`! z2!wLf0j>!>Ka2g@qo!A)o5Ik>7}QUwRW3F-$ivp8$KkXO1>$=*rQ3{!znpFFJD&(; z`4O|C_?^E9W5Ych1ziD%5%NhEH;B|Z!4MREf6?N-!B*TD;tGoiXY`4LD$vTgBwYY8 z7CkEn2(!2A!5QtbX+#~pf53#Bcq^_^j;@Qw_{-4a8|ipz8OzI7(htrmjz{jB9^3yTF0~Y8nZAOo*NJVR9*XOazDJR03y#R6l35B#A%yfY%NOgJzh+Hz(j}#Qx!K(IR63+^=dzuD zYW{<0*r98666zu9(^u|g^GfIS!4C(u&_pF@VclfwU-J{ICK4KPY*Jd0FG4p6cf9f? zBg91xzVN^hF3sUT$=Wu0&ONd9%yqf(oUqAwA0v&<9n$|O>E8KU82HFtMM#nu zruT5&rp;ef9TL`gIp=gb%nYR-&n$8Aw!Nj2Yked0NnI`o$J;NNS@y1G0K36rfF`R? zQ-=sH`*kHfCNE?zPd-oap2+3|218XMk@q=#9{j1no?4V9rgeSQ(`0-d*sFv%{0dUi zW4}CqpvkoV;HWw)qH?yK{pg`;m_lyc(xHKlLk#)Tiipa%pu?-@#Pw?{8Mx9(svn0kkQvgZLItxowzOV zw>)y>S}*VSRv8|V7vbgTFQX2A&TWi#Vy=^Q;nH*1jM1E-LDQvvRQ`?)@_d^dngvo= ze=MYtlw307^zvAl)LNQdHO-4!akl{EuYcT6206gSzYxaUet!}my+Mwjb=RWnLtyBN5Shr$nwQPU26*-SJ~HO=+vu*F zaKRxvFvQ3zB;U+I-4Eo&Xpzp3apUNrQAFjD`sCU4Y-K0E!gT(~UOBr1kmtuofX;)G zVc=r*`a>2Yh6)nUX+L4nwGtaOs6npM3IF;*N+2&pf*;x2*y(=`xVp4e9zn#7QKh{7 zdZMbVdqh`{6uRKClC#^0ZJmn^Jk@!avxgg!%3 zT3vj8Lqx z0^##XRKag1cTpYx&|*X*WGB-$(@9dY;i`Urvp0_AzY;8O^F2jO=!d}_b!4PY3S-lvzjP;XZRTi}TjU$c#7w-dmH@bI zCN0~WEpdA0Oh*3T`JE@@%c}MRwo}~R8zv61R1Uh-s#;yOcWfMlI2{wV3nLX|>yn`I z<>14IH2Mea%jDLZ)QP+g%l0F zf8MzRA}cH`JQJ95x)5?Vd!S2bKIh^%)PTYC0|kE$LvFgX9UqBGgs$2(HxG(7`?BT& zVUrL^fsJBeZB6W0zNGga*}wVsXZKmp#A`n7VRU|H{Sb*E7**Dy?NEcZY~^*YGf$?3 zsK3XTzfGllU8$9@YSqT7M_w&wrfaYu^fWgN9PzsB-`Uc%vjA13xLP@OBv#_k9_W5; zvK3d+zh}CpQLJv~4ej+cojVm10D89A=k9-Ni9nXC##YJMsmq~#D(=`0B{r#SU4Qs7 z8_?0R{k|E1nHW+{JmAQO7OT_cRN|_@C6+*p5NRW5xI6~y5|Jr{?L!5DA-nZ6i+`=@ zFPX1rH4yJI6RRlNP0$!+XM-gM0iWP;D~0d*3!~EBf|;5uBiHfV^#EUQA-76(hr^GwvOLv{!lj zo=oXU-tr#E!b6t2e~(wLxY>SEcaKb7DN!7iVp$$!(&SKoFP4cr-fcWc+I}oMgkir* zVJT-{{r6at1s_8^G0JXe$1u2GX-|AMuKQQQmbUzvP>9%u!1bp!H@@Tt4d3iTSuNm{ z59UOaeWLd!940OL+1sxECfX_|W^@)UKIW!H*6?xfo z>q9F0&HXp_OS;?jkCMs2=+!3KX2{H)>cIV=VA@0oi{gJV@`*|1cDe@^Fqs?fD6a!- zSWR!47?~A@_;+$2J5TYDn(AxKV@~m-3YQEcdb*~`LWpmF{gt*);(L#=FT{7xVTkKjc)q?%g*ohUe|C$G5$TQETbEFw5Ov{dE1_ zH*VLti!qn&R)g8?4!K9Tmde1}=^d0Bt%7&V?duZPxlU}Ft`WnE0Gs+v5w{@fFy?b% z2SJ}kQ1D)+a8>B;o$;`K(Tl?Hk4DXp;{dw*Gg9{BOMRX!uGyMMK7p=9=~ zoI9gV>yB5U=YQ9wxeV%eyeE^MD(W8Yxls;Q)GI~w@+O$CzVh}v7n)i`>Ki{fDASD! z!|h=;!JfC0U9#h!%|Bq;tErrF129(fj}O~MDxbcMWzc4>nU%2Y@smTG1qw&MRpPvR z)O{y^pk?(={bCLIima%@2s-O4CsejxqP)xjeAqMF5ujX0oi74~<6qRQHtJcpKy>T^ za;Fs*9Yni7vR}v!U&lzkL^MBD)YJ<|8gak<;A(d`XJcA=;&f8KSW;s{(8@5CZ+`n< ztJ6kBpesx0|0VRaSSl=Oh~=k2@2{D*xcgbM_~fE+O$k&8*m>8QHu!s@%4RR6>U)#S zs8SZjAM})?oi~PH!B_SFvG#iO@UK5QVW!HQez4bok(k_~~dGvSqbOLn-ao;g$2k*^~OBMto4g3V*$e`n~6710N zyF3_kA1TwO#(jcM%@gCPUepvLFye-<{85pQNq)-C+IK(fx25@um45R9SFnsznh(_8 zZ%c}jJ{0ycJXbSnng8qqlgEXS2V$M%{Y9w&vN()uz&<}YgMSP9j4{PEh)Jzb(x)%q zeBt1#ktF9Vr9b`jb@I18npG(?(OvSSowu~Ywe2o7m$|g7>stat37c-4E@U0D?N9%t zk?9$@85uT)6&Wh=t`?bz=`RK_2sMt%YeCtAm4wRCF;%ZmfR6Ys98*RL%ktK&jBTOp zz3(D@Rncd+7?s%6=d^P#q+`aC@(0iD)yvCdOWb;_bz1Z@g7LUY2&R77Qz7JrW8sl)0R;8PUP`)f=>QP z#=iJftoha}_a@qwO`?OOlZU@8TpzxM8Fhzh^}q5=pCs_ENxR?70{h9InY{HTEt#Y? z&ILPXvPwbqpuQ*jN1)M+1i_AV%gh~H*iZ|{I??uH`LkbqCj^=UJwfO7rmtR?n*KC$ ze6n=!td6%K1@9HE!dJmaz<;GV3pMj?P6O%l+`%K`ZaNjGYrMKVJN%g#0GjI-8CGw4 z!eY|{mu=l14?xs9Pioa}A6iZA;){u5`~*S!Fpx>^yImu+Ud4j#_OBBKU=_$&QhV*~ z4><5dzK?XoKP6~qek_8+o?IR;@N)rM7Nk!kg{Ar0Y#kZHc1AWiu$>cmE}scI>~nKW z)_+8$?BpE4K|i-mw-q<2pTa*BFRm9ha(YIR1;CYDsG5&`6)`2YB?jgNXqY4aSZMhV zo+4(4R%^duXun-^gkF21JZdTN=|cq^)jTuFlddX7kPbjm)v6!Tawx}WWt%8qbF|#A zHzzVgG+fy@8l8NVP5V=)D8i;8#?i!0Z~2!rA=kZ~VmDXbM&(ggh8p*HJb|La`=j~QhKW3P*>UkY#9FyylmtkY_wTINHQc#^}mOr`R+w4+t zXGgTDS~k_~cWAb+TNqan&NHQRZ?-fg3LV@6et5X#TtMxk31XEU8PjtsYddiULD|C7 z35Yocw@CqC&W052o~ltRSK{9`o(~-<27B4_4u=YoL~>q6cZM4 zH;>02eCHk$C1y#1t^scfu08^NxpIyZ+LDzOIr`Er`7unMld|%nDw&7(t&<%!FQX?y zU1BR}rk_7k0xw!%{V33BOeawkEv~W_cONDHVl%4ebzuv7st+_zssfWIcMY1wE|7}t zD}*2PJJLcg=zF;uj_2oL0zSu_k4cl!;6}6YlAcJiW7?}7S|_uF9$ey3KSt6FG*Z8F zCY#GPJdlY(EiiT0jy!4j2n;uM(;)8-62V>is)5+ey2e@IB0x8J(kD6b;_>Umfgvd9 zr$p^xI)B+gQ?fZLv3_q;A8*Iw4Z($<6J#q7uE*leLfry>zdu+T2l?M!5|>(#$N@?p zOlUkoj%{_-_7>X_-}W6!!&mtk6Y?WE@)1NsT;*w6G_aQ|GseDU#AV0)d^q3SCZo2b z#k_ux2U*lP74d+$wA!8;}(udOw^3lTY*7j6B8TL-zg#Pv%TD$J~RdDc2 z+^VPymlRF0b>tA<3|eytA`UvB^^D9^NK^oY1WZ?0Yn|L1d}S!`zNe*~FKZ`}Z(}#t z2na5{fyu{|D3sf-UUq+q;&)vyX!QFFr0SZ-(4${)@O079i>$#SO4zsYp9#aKn8D_i zz|FzA-+*yh67Bz2zsYU}E)G&+lfY~r@0({99o>Wb zPDf@Nl(jR+Grs!Ctrzc)CbP0<+WJFN5sJX_iZc21)=c(bfuG;FI?6Ivp!JEUt401F zlPK1jz3+*ufr{(Oi63DD&e97O;U~^xUzP(9?fjrtTIa!Y{9$BpU_R2X;Ar4`lI747 z>MMmK=bCt$t8^@nfg{X>5_iE(Xbl3#on*KS`HFY@k}OnDUELgW>G7zx5$0njbNZ*n zQNjHZbNQvmrVd0goH{SVpB%>B?+dU8ZvMLs@pop=cZAyZl&D3V%1+LKcITA(CsbT_ zYj?ZZa<1omV8tfidc0$<44+Ye`bztRgFO#&^)%>1V?WK^>WQF_+-fdS>frsYZfG|%h+1$gcF5xfwtEKXd%P%AYx~17@vDzMtF3*A?B-k!WQExbm*=2* zXe@)sklHVg&#dPcoIlLlP@#l%GC)&ty0E`vqPwx!M@$}_t$al!(rIRBU&DTN87q7^ zM+Qgo-ei(VZL2o?&Jq^P%RqXcBqcnf2If$FYa+;jF?px%pi4$n@BMnxzD;hp#n58c zp+cP>2t474TWHYYt;m=8QWQ+>iaUmvaN5N9hRg_CXgZ9~X0t-%XX6Fq!PRDp`RvxE z9EO({1YdB+cnv=H4pfCZyr*^rEX25QOHeK4=hzyEbc#DTHpm;@wwq*(j1Baw2I1dK z1wJQN-bQo5{ndDN)(8e6QZ6^LejS&OTFgv$-ZE(RkKgy)id`Kqw8^T;FZ}kFR$K0| zmiF`4TB>|?0TfQBlut$vbl0FKBopuHb|LZJ(QH7Lih--aa6ZOh3I&qd74X`G@kU6v zNNiJltUH5Kmjzc0PSYMy(AUNiP$8s0g|PTnUF^VtscG00jZ56&;N^D_i2_Z)!*W zWM@=Qr-4v|2NaIujAUv>KMwX|m#Vxj_MM~mGmR$yim^$Vh(yI-;>u5!h_2a-@^8$D zD|#N?|D7__?7xL_SJ4E@4_HveLa&+08bWQ6M4F@%q1Qd8kkFNr=vBN>I_d{)`&I3)QeO#Vc6Aene=T6dPu~aKZ zgD%WT5*Lah!B{C?#G%z0cQ`KU*sS$loBN)Hzo~QUA-VgP|3WH!%!XYQ4n6IhuAwBZ zi)@V5a}~m;5^lml1jJ44EHG&n+3^2l|N5LHmLLn6+c99Z=axa7j{V5477<20xtdg& zIJD&jcIAu-)bd^F51-;BBaSE1%EUXo8oVN(&mZgLV#pguoEO>l(lWlwZ#*a^W@yr@ zqR&1d!SxfcP84rt-)7hmdUvng_PaIu6N`D;$K8~-DEh-D-J4k26fri0zq1nsvN)Gn z@hjhkFFk5n`GEB4PxAW_0=}o$f=}38=KgM>YL?Gf5L|o?RM8Gw5rLjoBjAqBu@%b- z>M7aM%KKx~*1SM#m^~rUmJ2jGN6GkBoSv;XHrM*;<=NJzjRRodvd>2KCgBCplN#`o z?Kf_2ZqAF8Ly;@#^qD)jc?pGOJQ6ke#6z1Q5h#7<3`+r&RCwja%LSlkI&n?Z7zT%4 zykv|h%rlU(!)HuuPS}s_$sMwYea+*QtI;^ztG5BY%AaQ3w-}}2bKQNgX4%F&ZU4c} zfV#?Jm`Q88XcQAD@ZKS$Nd*>7>Pk8p>)iR*HWwGV*4Kwu=lxe9cV@CvFS~G6%U|AK8z>;TPn!3w{){2zxv)R2 z#mXV|;qaZ%85f^Ek*jmVxpSb=W~eDE+Vp3_eO&83?{`KCMpe>qU~4HH_DXkwwmy2&@27yzbN)v4xpA&xM_@VMIJ%mYnCPDUgniW_ zXTHR@=d|zO;N)g_*7tW>N5?x0InGPA_ob@vUnDl2Sdwg)1$bmLoe;5ANLG%&}WAeqr3_nD0SW$dA#35@bfvH z-=^TV%D(Vra!TDPz?kX?6Aa-CpLI9r}9D|yB> zAqqnW=K0{jIxRlSXRu59KWhfen-mzfp3jqy$#T}0spDKp?wjZ{f87oTs_3UM)nW{l0)M?l1lePw|ztzZeUq zFVAf)sjqhu&>oT#_h#-d>q&Kzf)JfvG3}C%3E0QrMaNlz)r*ZSdx9X?}*9(AIhd$Kh{Gd-^!`e%X)1xd@{n>CSt*7D4 z)X&5sy`#lv|Z?! z5N#%Alo_*|CAFzL524+8i4AnP-7}0Gdv`VMQFd~MSvEhJ%y*PuY0>RLI5_s>vBj@Y zf#L1kf>H_Bv4?6y+dYLm3}?a=t_XR)3P7#C(x#3V@?}bI3M-3WiSvhgh&T_^m+F>P z!pzLU6n`lLgZEU#;)svsyH-Dd?!*UkQeN8|KWVGP&QQ!c`x7X*^X}@Sd<7wI7eTK#f*%Ij$c@ z|Acjad2}d(8uRGj9bf?$@(!b?nByh7$WU-mO%~S#RB&p_C9d>+zg{!g(ky8)9*eln z?rd`IQ4HHqX7;Da+b<8s_yuq9_SXtnSETewP*h1z#d_A{1Uv->F77=?$ETUoio(AG zy0f~O37bT$=$+3u)*EWRlpmIF~-jq;LmaR!o~CRU0fp}I8wW~Doj z*LB&1OS84q!$1K7FZvS!ZSBG705O{{eL%4!{>QrS??Q=tFw5*Wh0nh3H9T=+^me^M zCz)w`yhA{4`u<4cPc7DbcCtEuth|QED?CRW@1DI`e+H0e99#efy|sL+^1~VlQNvHbV==l^V;vpz~W&`%yEF8By3! zOEHs!rVz!~z*1BbyuA8%0(8mZ9isv9a^edC#xz*5;pt*9ERz+V_IrQBX^c!Lg@tqFj%%es ztN-}X%q)nuDue2T;i{8@`vO?BR7UK5x*cic`;`B8S*3a6sb(?9dA>Px@db11joL*T z1qgJu==leNb*~pu#y0^SyvR+=3uH&}7CC=uO4S7Obl-KLPB8YMIsaF!(`HG^$5v3o zcK!0@#o43|lIBT6#z!BlSL^)^-$Zm_lF=y_O(?mUqc_-VV&(zFgU&-Qz*En?>SmdK zIH){%U#elr823pf1zNw!G5_3bDE&p5`5=QENXX{lGtc-jj~HNsp2>?FR~;bd&oa6B zTWO?Rhb;?Eetv#@&M0k)$8YZ)Yz(#rAw50LlnO5~kiSP##=+r;-|6}FOJ_k^6a$aI zS4k+(bLq9gTta*rz5$fs(Z+a`OgN48a5Kk3m7}OirOnwaNoe=y8x;QR-~@K-KDgb` zPRVuJa+DCup(Qh%rI-cO<6@61999b5hGp|>lnNU#R{NgmrIKz!OAH#2(}?LiVO-U{ zaXhWl3}FrskM#<||FDEsxyfb+c#*|QUs9RVrskQog?mpmY^K3UjiPoK0~y3xNssCqGG)38Q*3<9U{k zh)0c=enPmS45S`Ut@OrAVq#(*#%w!y?g`!h4~upmVHhSfa@5-{$edZPXscSw*RjK z`#=00WasaLO)vn=tXdqbJyun(N*F2B%2JIH8UznA@076Yzmh(|45!BwG!yn`>A~gk z%+pXYJ~OQdr~hkzFblJw`*D%ZeqUl^1oR}0`LV^w$G3>dfP%u40A-D3VDQ}P)VQ_} zVKIFqHt^Ym%{t}v7g{Q)L#OUW9KSt*6ZMZd-vu3_$wo3GXz=MA4r2Bx1Cb6`r;OJv{|CZC2%bE zO{AAUQm+E>*jZn&ay$o>g|7qu=JVV?%bL?dKCHa370E+AWh+fuZM6&@S>qid$4X{y z=a{O&$nSMZBU~6kS-Hw+N|)U%t~T+#pL^$k+}xy($iwv{==I=qe&_8s1?)xr(WiZ% zl;f@2_Rd#_$I<>;Ec^w1+m*0xZmcpwiM2G^e)%FbrLmi6pwFeXcuN!@@MWC_l(K{9 zU!P9u4R2gU>PP|q>po1X9X>sv{9dmOEVaRF&hmC&5zpy;lcrcWqjU-X*F(UD0i(w1 zb*<}%Ub;`#rRqDD#j*_rKDG?n5ODVR>mjpNqyG{MjC-U7nVLuZyPOPPx~(3b@|{*N zTr~MrQ5@CHJ|TQ*QgPR#CN-6NqNj)JuT9vmu+$rEfHkY%R82(&EAJyeh0%9woA8JH z>y@jw)Z=qiiId1z$?>fEP^!V*zP$_Du0fP-eJ*-Xz;L8p=W z`LJozTNkLdUsCF&g-BqK=*%FojZ!MR&+2*i5Q!>S!cq?>QnP3V71z7z+oBUXhsZmTCNI z*c<(ou7Ul-5yl8p&wvd7)5@7n3Aziuy&o?*#PEK-VzaCwJ7C%p(XPdlQBt>44|H4) zCNKcAzA9zl6|P^N(c>N36*CUOt1&Wh_wqHq9~Sgdthpyq4e|K%@h)JF;N}ZE9h|a7 zFNLn=0=BQ*a!QWj5wVVHS&U40%G*Mv6V`94F=}c3VH6_chjZ?J6NM11_}s%p1>z@$ zy$>iLcHR@Ukad8Mc^o%9azO{Y(0J}>l*gKUVWYB!ZXi^|b2lU;j1o84Jo}8t6dlD@ zbz{Vsmfh=G@(*)+F_#lAGG(QVu-|7B4?x8-AX;&SdyWtsd%R|9HX|mvz0*h6b`WVz zJ`t(#Tx#Lu-qgf5wX*1Og?)o5))>Wp?VJl%d%tSaMkLXo3l>G?yWD!f7M=*|F$WiQ z5S2Y1!Trk+7IJ7NMw+FQ+#O_7BOO~&b@zMCS{hn45d=-*QaXFReAm9qa~K%lg9ic} zsl~ze97}L4@yPk#r$GTrN}k45sQ#L){PR9NFfEnay3--0M;{FspJ}-y!j$3b7ckhj zd$y7e9*5kYZrR*Z0Sx8|L@&#myMxHRs^x)b{DQT>u8p8Eu zC~c+rpx)uI48j{PbaU9bq-OdYvw>5IuGVifn9RC{GoEnI zkrk(P*>Or~nRWPy4G;(}bL<%?zX5P#wQu%ptxyE0EP&8nQ|bS6z3N-<>rA&Ppjg_g zwcMJX2T026W$z1r>lAA<4S0#8wvzF=az|BwKN4Tr`{{+ordm88QfK&+(BIS1 z)!puKg(~7?{Dlkt00k&pN$D~OQ&#U+v$N*xo$8~_LHD>XzdcKR;>${tY7fWi5-N^= zt*3DOUtZv98{P=LvNDCrb-!&KZqkCm#zzLk&VGf{Sua{fhlkT(>xl#*! zsqS_NrxapKQ@eLh+EVH6n4d9?wM&VU4*a9>N3l`b3~012@m(-&l}>tZw*Iy0NeF_}*Z^sG0B%=EGN zJ?Zv_e4|3UteJB)(21#3&JF0ZG2UB@%d0o$eJ#b@uU#}#w8@*esgo1Z{tt8*SES2o zS=tFmgDr5Zkg*De&+xYcosUntm1%BUxw1&s#1Tf>RZPHG4?q9xO;6%cm5P1RQqgZ! z4$w!lXK*d0V|9SV)HbPsht`n{>W?N%=FvvvOiH+_Ssxw+*Izx+6G&6aAWh zm>2{Q#cN@PcYn|%9H2_;nkx7|sp696BMrx!;XrK1R(>`Vz=MkiD+Ji}5jH6ZOc|3Y z5cb=@bf$F`-}HfDhxPPS*4$!|teb3#B;4x8cutunt*efsIrSYOC{|f8-U6I=>2J@d zV(^O%thw25?3F~g(VVd|1~ z6Wc>Gv!A~u!Zri{b}0RaL{s)j+!9BpXBQ^*Pf16&qfk`XoAjHM;B!GQI$gII=RXQQ z{&wr7iRk~(Ag(lzruiXf5M&06!odxa^$462k~+!yuox$%GU1l`EcOz(tjN?(Q{3>) z9WP`b2q{H6Sc1nQrpNcLU6LO{%d}*bOchlgOIJc&Wf+CYwb5Le*t0zj2C0wo8)e{P zjT=Ygm*&^pO6ZEPp@N%zXCVO=SB*0QCu|Cwu+jfGVOO9J>eGy!S`Q-LWOts#fEfPp ztjCX&YnPaLQ2J5J4#U?ut!!+Ly!a6H6Nn(*C1k1yYDd1fnNv-d+6)Myy@8$FFJ13W z4;ucj0U}Y&6^va@kyZ&+V;vFTY4-|FOs=85$Yzr-wu02LczX3Efj7p~jB~738ENzn z`xmKJX>atgOJa;Uoy2bnx0N9B-YU^%)k9(PmFIVZ&8vr*dhVQ(j(iSLcja+urh-Lo zeeR)KU!64Qk-0uN*(f7Xw>j>2&jd*mrkoK_+I~_pXz>j>bds4p$Sz@9&7BWCp_tVn zt;j0lrW1L=65VfoiRkp*aP^rRKTa z54xHD$VavL*2{-+|F};UlLD|@&AJhxre92LaSi&AM#Wp81&I0Fx|X^u#Jd~xtw&!x zrISHxh(mIqK=(!-w7*h$c&I}yLuPhwk$+Nrvkh@SY`;DO7Opat<30XBni&}p)9Ni)u zDP5+86@XSoN%RF)!3~Jx_17P^T>Khk_SxV`PJ*~QwVYsP;8N}&0$X7(LeAAR$&(=M=^gN)4OBE{+!+z(atjShSfPO zlD2z(8Y{F)o3t{ou1JPvD5;Bq{2h24qEpG~uEjs(2(x%53=xeLj|ug=HLI0v2KvkL zjOeE4cM9V4gA*Z-($K%CbhNt=_mAi})5uPhJ^e*;xYiMQ$T4}VqWc7+;k^mTp9`y` z)E z`zB->x&%?rYf3}|FiH~dU5N*~IX$DA3De>y@(>w~1a6qT`c7zQBSiGdFEOOmd(_bk z;%*pq=B1QSBuxXVI>)2x5!8=J62IN^zBIIFe+n++ZcX3Qg3Jlvbn~@NiLW^F53iGH zm61>H8a91()~BZuWlEhrQXg7p5Zx_D;!#|TjM@}-&T^f(dMX=}pWgb3@L4{W0N}u6 zxlILxkdQchRf-XbaSG{lCEi30K$fgSQ8r*Ft0L}bkZbxU9eQ>p6Loee6ZP}jS!TBtAm}7ec+ZEt}UjK#nrlvNEi$>S(jK^usgV0=;V{ht(?^ z7F}Nol>GKoDF%;Gos+LlKF9D#YEQ?bRg@}~KjXZ+!?9#D6KhctYAeh_xY0!oYf^W@ zYSF2{9K}X8><@T0)Xl-IzvP1(Uui*u{UO;R? z?BR%*C@-^~ECxj(JHnD`(;A0-xUHZ`3;tmw-Bt|Y#9Aa&jCOCN*rIm=8j>vVX!sL= zpNj%Nc`5eGlefpEMVp+4*Ps!Qhwm>`Ol87bo{b&GKXRk}k1+$Drb-$ATR$XbN5oI9 zit7)P@uw8nO2TnX_&>t~(r$O)+#l?&dwA-UIS8BGF5~Rh$-Xd+VNK(O%Z+i7HWiJZ zh_zk1YyQBQgz_3}jcHKu8YGM==Jb*pMt%*Xwg{oGa!Ka&HP}Ov2}}>$O2jY88He0> zn`tmJ3iSw|9<_T?IzyoHnOgg!>oXVu$t9ENyTC!sVhY8f%rema^}=WdVQPNL3Xjam=})1_ z+5P;i_Wr9qJ!*MDnnv&G;1LdWBoFZt3Eid!0P@(R#B_^)aKE*NUpuj|KmgxPOjlvp zj^Q=i>}jP3CT`p z&SdorcPDzc2 z*D=|j^bVirV_?>pdqYSJAl3ecRLhXZGB@u1U?nfUP&{P#WSk9%M+zV$hwFe>sLq9r zHwhiK*aD1$Sz{LRCQv#ywH0q(%a-;hRFm>C=sN*0jQfM3Q67)P-yBy(J&Nn=*S!w- zq5)y0BgXgNv12VlMVE8PD54J&Y!=P{si+yx) z$K5)dUb8a;?vVavKZ96!-nk((R=5x#i|Z3b|iVoFzf* zljV(m9V2zGWsHhxI^9_`>XX#$Ko3fuBjK2|%U(1g-=r2Tm zEgX)oP}YbEc^va}@ze^+9&`Aw@6yl>C};anp4Tr%j&+S;=~o>$f@13Q=GMaZ7tzgs zIPf;$?N!wO(&4Eg^@#`Vp#+`_w7Ksc!YHzbfOu`MpA^_ieU#;KdD5$XxL%s;z+r;9Y!m%6;(%2a0(t0Q7kC2!E;lvaItf`u@r)cW`!40rMn*owLGxM)o5YBY zNhHJ`j|zJU-I<)m3$fi*A&~Vt;eC6FUW&YlcNcVl?C?CH??gDsf-TylOWo)NlN4Xv z+P{&)V}1!=ra5mRD(-?iBVc@+(HS*i)T2e3#5YN9e6M&m@qDPc z2>KB?i=~e|F+Y8!@m$C@nzHmPU$unOBj$O`l@$F&O}{MV|I+p!3Xo@F;!_}O8vAI} zpb28vE-8_sYM{O|yDhqmHpMS$fQ~w`4=ldJvbjhK$QOU~Bb(`x$C^RMIR5}og+ciD zv+9`S z<%mTt&3??(=)ebge7kwp8&a?i&xn`g^peIYDRx6RZLip3o(d*r}tUhn6K@xh)B!7FZ)Rm3mueXVTX zQ|Ra^jgU&R8+4C{x`sRtfAAglU>J$M`eFld_Y}vY_!UJTPOi*inqUz9aS|gqSUu_v zll9>WuIM0cM61#6?g_8!N0o^#j+l#6t4C3C4r-4!P97)iISLQIVeR=`-0>L@8t(DQ zn${ZxNfvHP@#x*_a9>EIrJr>vcmyI=(`0fZPDFeh%5zgTAY0Gp4lKtcf^mEX!jR)&&ySuog<{@0hbQW&59z zo3C9uhz?xuoHI$PX0P5ocf2v5L$U(0d*iu7V_bwG%I|7CT9{eMyY^ipBC~7neJ)6P zM?S~2@W4>3h+Ke!%BSFBM<4&4V0zDXIU$pi0;L!6vx*!mf#YhMlIcKpyhRCy=ToOF z3ny!HjIjddyYq*3lRWo303D}}#$34~BKPtk`iGilO7oGyrXq0uh-C-~>MM1y=!(A0 zXH;E7^HevuTu7&PuDI-0ORHYrL0s$HGRXmiD^Gl?&V5gCt>dyFMYg(N7u}VCsvp@o zDUY#Ojyd8E^;(ST&BTml(|tchiZ;Z)dHP{^;r*xP)azR;bt9mF77oXaVfGItYznkj zq`?OfQ&5bF4jthTi|vt5L7=C@{X-i!R-CN(>B#b_aMEk>Qa1lsS(kYIA1U>$ zp%=SNI8_(PXSZh+&_aw)MLVCjQC~!1zZ_LqqziB0T<|l{lCz=x(u&_oLN}}HAfa_@ zh*P|bt1atZjSabBxf_v*hWll4=O*TD`NPlJ&>8iQHISCLDMR2Y^zRNTo-U*P2UHpX z=G=oK1Ahz*V!>Bi@&P2gQ%I#|?>zJ*a`bK-%+(WX>Hs6aHKdh}re#|cze%xgoo>bN zM0MHE_48bT*yrki(4vx!5^cIz=8;p-q8&rnI`bs)k_=e^Xl1=);ry<=Vnux+H3|L9 zrvEYYN|pS^%q~YQeHZ-*DcI;0m+9%4)fG3W3bx|Tmi*5Cv<{Q4(*UtQjxckd>Ow>I z)s8geKAqxkcyG++6T(319;K5R*KJn#(x_216${^#y=W?!=P$65{OC6nYIrrCw-Thg zkyW%W;yz&E&^zm7YYvnnD#3$rdY-kMvGjlM7o!n^VpyXTj^%y@&gqKIz8HSOoC5)@ z$VL`Bc^MtSe>cPFc~X43N^v-U!*sj;6dUt?zE?Af< zGGQ1w*_&nbvNe^5VN1#(EyC7EIL26s3`-d3e)176qk1q;jz8KXFV>j^m1TQLKj=wj21e7}#;YoZ`hrvwQ+Tx3l)F~F;xR4K6 zQ9p;D$(_axxY%KEGaYl@-WK$397^ifsB=>MQoJ#0CT7w_H~EkI{2Gh6PHOX;`#cF{ z%P@W-r#lvHFO)?BquJBB{fvq{rpvxTt3ursGdjG>mb{qL5PNCs6a#vdTCwD)QgY4r z+%}5hW0$3Do`CzMxRll|#luLzG8h1NSEW4&%aI$UUR)4#+Y##DFKFm!&aaP_bj$Tj z81ujQpR(1FR4kW_b^de3)yNg+0kd0HOxahE&zpN8Qd0}#_7P9KGs-z4)`|Jzy&Gye zELCE)u@*7(@9xPT7k9eef?gR1)S0|*I9w9Z0S5HIce-N40{$>9y}^PxZZo!LDZH}o zkeRO<^Ux^tp~<5(5?6jFNf6jz=i;)4;{9KR@oL*RB&DpZiSk|CSF<-R1UP13?V^Y`a$2voABQS!U4W&i1jz z?n)29vi%JLd0GgrK7io;#Vd~8ins*99h>R#KDzG#m@`tbxJ-L##DRcqJwnnY;;uD@ z7@vtU5+Au7QW=N$4vmp^9&~;Q@aHzs!uz2@WFpj3Bis{=+f>Qhx7l6ku(wF+uq1S2 zKJlaP8+l}M{^Q0dxjR_pwlwgqbx`>>N$k^buB9!jAN9 z!dlFyrCV8F$Jr6)BcTp;?w|U|$a0~6;*E#wIFQm+7X7Y(+6%32x?$Kj)`m$q{!|HY zyDo{0dD%mza2bC?`=7TZ?cuO$G4O*j4Yl<1-gA41lmx~EKk7k4@15t%o`$A{;RWdF z#i@2~mxqhc>@Jcn3*H4>EhkmdUzPSiSu6!`4gh8Yr(H??b^I+Rku=PUQL5CrICqa&@8aOiv)N5 zxj4ywHM{WO-A86gryk5Ctst<*NXxhG3xnQhrt zf!|2}UdXeAs^g{H+jr<>oQDPlCRqA*(>9l=`xfW;Hc%}vt>aBUTf66m` z+5w4L^A~#Wr)Zj1fCeh-SF)b%-`WXVAac1 z7x5*7+rQP4jb@T;pt~n_0+3e28xf9B6r4RRe(r>c>A837_fZ|gR%ex`vK$(Opryvg zN84T2xgd6u+-E8tIAaFk$d8Y}f1IQ3p)Tp*SZR9&e87CskfHD6KZLL?D1>)~{}!%#9nV#Kd11QyMy~6>`LY~o@UWE6 zzmm-UShhf0?-f?(&^cvY2d5R$Nhe%z&dvPf;&)Xo3L(A7KeL?-3A zuv|L|kIr%?X+3=OSv_csAFTBmQa_Ea>c{v>IA#3R*eV#?4sGtK(6<&+V|PxB74%~) z2MaT80u3h(0w=-}*kXLPyrKJN6QkM~*Phd^VB&_No!uDlU9_2Fb&6}>>WN8EmD_`; z8JB3ee~;y&7=)um`u|*mB!IVIq))SptJy0?)lsQ1cYr^eNx$OhjFMJwiscH6J)=7;@UaMB82r>0~x_%_~tkm(jZQ8)#lphNo-$AZ&2pj`wq62O?V6*=Mvt zzdw1%RrLEjg`nt$7GI!0P41*z1Qs!qPu?2DvLZQN_xC|ChOlF_&=YdlS8c?z960iVLxj|FjB&e%S zTI?UDRxW5&6(tJ#J9vsCS*r6DqPCCzI{6_Lp`bgXZ!_;eq}I38P-WAAv(;h0V%!Jv z$`Fa_VPDa&_T2rAe{!;{uRECa85g{Pl9D(-M4pV1@-u9Q3pqcrE)&b z%c3zG-0|tJSD6>QNrdo6<1*Fa{KGqXa2=%nEfrBWK`I&#miUrZ4O}O7Lnx58Q@|dt4qwI#@hp z-%s6wW&QScWX~6?I^!D^dZXDSh8jNSetor zi%D^~vpHQFzN}~W@Bn%s`lK&yp(FMJ;ihXJdTpDvkj5ok7>2%28Z+%16wD@ojups= z`e$5XorJ&fOj>A*bE7S9x#RuzMd2l1;hT#u;YV@_a=)s0@-=GdzwGY|Ucd=|Rb5p< zn=9k9_TJcVUq^8H?3r$scbt;NUD;mbX=#^){zV>;0J-tf)-WWkecU1;a{r$M*<5!Ud^K0dq5tC%2q`!SZrQQr(Pb}R@3!CV4OWIuJI+bJ zk=k-!u2vcvUf8Eq%eULI_3%zXKeE2`>$(Y(O5()(V^gE%SrrSWI)470U*hSVtRe@D zzjM>j!iI34W7d7gAFzIQD@?yEh zf*1bTolSrrO{cL4h%;`ol{YRji2)hj0>JrA_rf*wMo9g+H6tKnjcG7xCcLQwzY8QX z0qhlssXIVYf2Rw4*|L>|mSa5(7Fa@nx7))_{sepw7?2V|`ob9S*Z+QLe34$A^`u#; zKACeEP-6JEgd?X->xjxjnxpMd+R_!yfMq4&JWg%-$0*lktwJgCOzU;QZ@tnt9#XVx zk2;B2&1|Av>*?2M!s{Ll6Q&J;=Tb)KR2@l-ex~T!Kx4-AX-12~L~YnZ;J?D~yCL^c z$HdDZDNrw&9niP*em$C{wagl*yHt1Hpbmk>_XYCepo}R-ey`Hq007XM5}>VI;dz08iQpvhAyhogV-b#9eUtu-=GGEwZDPJuO@O%GTqEwi=Q}fhJ1T=zARWkbz zN7!BgE|;(Zi+!ZHkyQ1)!QGEuDUHhHSi?fLSmFwq2D+gH-U{aN54~U>(&CY$dN&mY zWhu$0pR7yO(fSh`2mbr}8KfO*IKLKZYdqa5N6qJJG5m|#06UJfozay-_9r_+Y-KQ@ zd7G&YgUNOK$!TFt-CrVN_KSYud1)jZxDIE!K(K@X~9gbo+U{TTH{;DLEn7NdtG8 zNj-|`;NR)aUJ)k=0oZCtW$mSn&b5BB0E#sZTPhiDLPUQ7jN^)T+x>4!vd&sgMyw|- z7RS1#Puq=da;}~{dZ-2v1tWwZ&CJWoYP(6|K1hyK9j%Se$w|;18fac%nF-T@w}Vpo zXdkWEla&pJ1T&%aHTE~=-N+8|9FRugZx0o)ti0hYFI=0sIz3gT%)$UU3RsoX-k&ff zZHmh5+a2L02k_w)iqRLxdH`|WZs(ez>b8#n>3(Xf2_S4r*70H*VgFiL`zF$o#)|5J zn*ix3?Ngct?yr@F1YMtpgD}S%6dOlcVu-C*N93g)UObgDTWfKBHK<8p;_FZ%GGs8} z!~_(I#(DKdL;<;(kS_ZwH}xV67I=H{!J>W7Yg2n21HPwuelo76*V3832Po&NZ;T*$ z2D1MI^6d*YfFno^Y_d@hiN7wOPOp3 z(wHtt;(9j-^Q%~jm#Y~-`L6e_@VDq^ke9mH}bcjej* zd9L0a0cAnv$?2b~?|^m#+w`>W%Lt3=F9bbj7bg%qdc#6>#>5Rh>BLr3uPUVr!wY{` zf```9@%|Bbo>7k+8?NnC@SQOGdm_#JH)`@gZStVkTm(Ll>YZ0y7J{8>Bd<@ZpT-MP zjSg1gpd;Lspl#2_4gKtUqF4dL5Ci@)ikmO`dG1h*)@S1rVo)!mcK;a_)~RS1NtcSo z=jykO*K+C5+kT#vIr)ln~Yr%==X0RI#=GTCC%lWNN z!F(wauOd<%uOx-eSt$(EP<;E+hRTH79^vVVuB}uw!R`&R@*w$EnBSr=JnYo9P}d)( z4RPO-t8*CBMR!hOz~opKb&7SO;(PP1fraD~{CqjcHdd5tzK}hUi@jBC%eV`NG2dm0 zGaTpzH1oBXjHhD$Y;X+#$syr!hir%rUiF(fCwb$%K2zXIvmhC?yLBhQ+`E(cZj+%( zkREAyT!b+d5lFc$n&iGGBYxBUtfB0PWW_Jyos7wBO|B)9$wSn0>UgJ2CeABC>lA#h zT?(5DP1;zMdrZoOsbT%W?_K+pm}hLr=W7fe`mA-dkeS#ov?y|_e}1G`()%f}^ag?u zsnh!{XyO&%#jwkb2_s0b)e_IL&jnNP-`cJ%vKu*V$hdzxN*F1EK}$s$e%t z^7$**kkr@I#~&ZG@F;O=@awtw7fyA3j+E2Ha~2I&vmr8AWWxR6sHvgzy!WX1f!t)@ zqF^K*2{M**JZvZNj2*-Co&5rLu|hi;{h8qW?E~9*a0hM}Gn_nxxabv)kNZ>Y0=A*q zDozct=ZSC_nn|QVytWMar#-ucRH_fTu5n)*VRBNZd6Q`AbHhCGKshmzpO{0$sstnn zjWm}MC=eNZ-blC0@cT(uNl0L3yYENtbP?yTsS2x~*I7j}9#ASPQ9{zS7!KySZG_0P zQyh*W@mX2IQ)_mf-cvPuA;YlrBIbnKHs(f?KH6e?OlEBOh#!(H_IXS@uiOdPej35? zDBKJ>1}k}p|4RyW*bmKf*kN+3fan$^rPQsck31OfJt1?vg0 zM~xCt`NQuv;e#M|Acq-Nu4aLZ9zs|&LfhKRLUK2yJ&X>Dfr^|}AfX-2pe z{C_d`-ce0$-P>r8E*+F2fzYH#M-QC@6r~r-p-71|5rq&sNa#qBUZhAB5j#jkk^qJ# zgd!lIAP}Skh)54L)NiBbeD6E%@4I8%G42?5+<(NBy|UNZYt1#+oX_)2-*t9`wj>Cz zAsC(3y0eQt)o!YB8wBQtbZej0fN7W`>+5``pV0?3 z3HieElin467Y6bC8h%8W^CLUQ8swPeNsbV;o054eE=GB^MV&rk0$t(Ed;aqaen@xS z9SVO`<6`_@uaaqD%Y@|z8Y2XUdY|>oaFMi2{8BSEXUE-wd7mPvy0w?o*cTzXw&hyV zYV2+wu@2+v)dMGRc;C-c+Qc>fkXuWie*3Fp;$ovqa%&wakPD@LKtYN&BVBEOa4ap= zI4)Er#vE@_Xv(_t^LwFWN4nF9PQNDM)oagI8{K#l*IZK-Y1Us|OY}`0mO&#=^4ETy zxuF*4&*H4|-?JzqVTobHB0aPWDdpg%wB8(^by;&sC(DJoPrkEBE#6nNQpZ_Yc73(& zQMS|ggXd{r$BLxjNbji6NjGu9Gu3p+)|ljAH;dRrT}Sv=qP7wN6Q+J zKFI&<|$s9je%U3Y-^xw4f54i&k;mz4Nb){&o;6JUFnvJs6gI643p zC>;TS$wD&Spr(bh0T*S{TqT_Ae=jIQ2`@M2&y0I!y#H)J7zx@5@MA+wy(9-o-cnz- z$O%f>hqS^fIUdDInxL!QQ?t%R1a93pHx<;Tc}`+!jo3|vUooQ`OD!EUHu?XVEbZ^5 zAR`JfyJDB>)-+FF+Nk@MxmI%Z-p{CDdDuonl2>#hul$0*}3{n%T^`RC~2zJ$r2Zm!cZC(-SI!i0|#T+yd3AB6{gNh zObS|~IPW#@T06#OjT*!;Qd@+k-xZh|#L+t)K}$UiyFczQ`qqmj`;%+zgCvKCh5Sn2 z2N%+Fvb*ItbwwXfi_10O3odL4cP@kkJP?H4(IvO%dia7T{+>M^lI7h!O~HD)+BVF}z|Kk;D2cMsL~1 zpB6vXlKoN{vZ!WT{@Y_-C1!T;_pSCwb(WK!5_Q_ZazR-xDLjQ$c9K8LGBL8~0=p~1 zCO|gKwOljJ_|JG;vczQsmNnH8#%m0v{xHUJRmJZ^QIBRaRPQISh#AXnqzyFoxgvey^s&n-ihbE5A?Aff@ z9H)HBIqVz74xt{e=fRsN!kjD(vRixNyC)sP$m^5!NE(JBgKUA-Z_I>3NA!Q&lBq2< z2p5B)ziCFF1&(xL?{$-T>VMB1-r-b~D|VeV&r}oYi_(CtFXdfh0t6O;h$5(f08S0z zL=GFMyzvL{fWQ(;b{%lWlH4qDv-C{!j>7+CZ+|bL)NyF9t06{YER7HxBB}#gpc}dX z8fxY@LHXzool8htixUlC%39a8wQm&h1@@e1Vt!&R&%l)O04A{O6aZYQNxD-gjgSMS zM7g93G6-EPwuENrr2x3vUWTZyc^_e7|BfQjRddZ;MOsU?#pg#yjMQ~C_9ShPldCPr zI{m!*o5I3=1r>$(DPK@!o@u!wUP;f*32Pl^%StOPp7*nj(^hIfC*+A2m*faVq8pW` z-n|fOCES@#GUkl&l*?IaR^`{e66H(uB}vERb8HpJ4S1~NgH3MnMgHT~smx=u*9*Wr z-`k^t@0}`v^*QBXY;9V4*re8d4s@?r3S^2N?@VZ~rcz&%?SbBLr}GnpOaN?>MbcME zcDI0{h3dl!k28**n!KdhwtKfr;BpjtRCYX}rj$+kJ1qTka3?T_oPs9m80z8(&HC+N z1#5m6hgSfOX+WVYUp++Kr{Naem!Heutd$&N=mS()Kcl|UHyK5jwlR|~zh>=|(s*$x zDj}(@%KqoH&D?BKd}{YB9Vf?B*yd%MWy{E_A4;ZbI^b3Z$4C&*OKVGhY^&K2A3-lm zxa(YNm#i~NIHpp#8UE0thGx{Nc-XZ&i*?;;TCR%cW{3nWpEv3-vwD$0?u`xWIAm=~ zRW?7HSw-Rh?@cOTXJI|pb!V=}bs%HrFIo{r*7F(;v1=ppdyGA^$u=xTz_J_WaNU`f zG`XVUp*(|PYd;56P5!cDWA$GSAZa8E@MaJYcOdHAPOA}!UGRJ3Ftwa2xJH@&fVQ~w zNjx{6Ac!;1jXj|4OwJ`%BEVk@ME?T)k{>?s{j8^+%!c+#XUCYO=XB5kGYbe90LV;b zh@|;%gx!DHi87gtHgKyHD9gxzJIP+eP@*+uiYK&2tq^q-B-u-=sS9Tcw_+R~y z*F?jTsK6|~)_w(4hVr18)_)#v_5t_Syg1CbBUW&7%SW;`fGh-Oc&@0{O-v~b4rx|J z={`+)EUwPP!B0|jI>>UXC*P}J1xAh*aATHntZOYKv$^pT~zZh-Cl zjf(_8`Tyg-on`;M?|2!$v1~4zz7~r<*=CLsj7nMMz_LS*2YL!2Qn65N^;}|jc zU$bK6nglwJ^x)ZwRio>GlP_4#&_$j&DaH3;AZ?JT?!fY7Pbqz!{m$;b#)^&M4Sm0x ziE)eq%Vj0qDHopAOZ-Y!%?xOA7C=Z}s^I%fh35R}0=E-s8+Pu{VYAo$<#wsEZIB${ z@%)6mdN2IsB90|Tn4C6IJ?%cY_CCdq7vi4ze>0ds_zAex-%e5YnEIM+QRtg@v7iE2 z0B=wITFx6Sg`16?#m{L4)fnR7nC93Ke9_R57qakZ?rny9I*0cNH$TiSwO|<67g{{n z^KXQZgXj5gWavLO%S>of4rkV*i00}q@`wwqHeBhxNb04QR7l@-SnX0sc=Ie~n6_@ag1#KQHq-_EiFAK^Cz`E(%xRng5^KTcbGRXyqRZm>L&^~ZXm98~Ie?10{ zn%e4n19aJ&0lQrVFMfk%9UGs_u$=Mb`pxyj|2feuOapA_&p})cmhT=vzOXRqRp9#a zxIg*m--KJUeCXKks|!{AQkTYX?7sjPnue{007W2(D#p61AtlB~ROo5dg>YLC6`Rbx%&IBvEH^#N#>J=7Xt zD+0`MNlny_(p$UwoaL}r{)&>Hhkc?SNYGAy=QBqGnAw|CtSYFfmWqczXKe3sv7I{o z_Cpf?c>lHAg8lB*FYK$)BBKTC$1#1+XQSQ}rm-J@Y>D5ab7kV+YrVA09&2`wT}cF< z>PE}i41*L^uaRXosm}T@V8+!4ECuJvvfQP`&NQ7y5YNSt2T%es0IxR~${7}T5NFo! zSl9^6rrUx5SHK`|s}kT$0(|!{R>2|fcNaCk3C*MU`T=CG%n#et?XtJWgh=FmnPL;4 zg6FFQ^WrCocR+piQ*8>tm(D?-N3C2N!jkE|+l}2S67dPpM7)OI)^<&Br^+bKFQ{hw z955`i`F9(q#N_@R6$R!+LjXU2qd22Ch>J~BV{fl*OD!-j%tKSg6OGHtcsSDXEia*ttz-Sz`z=Po&1~Wu(#RuWt?pIHXYEO5r z;#p|z`TmhRkUqr@K(LRWO-wW2#L1IZgRlOkuYEh+KirNpw>G3G2ZoQolS7MM8%Ysu zjVff1m7A{C`t%o_Jg8sxz*W29FZ+`ri+4-_f(_xs8Lim?i--5D<^BN4eRrnVA^ZbHjR8Fv zpL*Bk)Cm>gRGRxj z#<4yAxmqf=8!Xz1v8UDRQ#)@TL=C$QqDC&pH8PRfv+BQdepO*l@@`5YXpvca(=KaF z&M`&+H}PAK(P}8IPwJ+dTv@*aW`fJOt_emHgX&dz+@|`hXukKvVdEgV zgcMpz>if?eK2vkAA;aTRbAAv05lpcx2WnXS)7-JSe)-Q#xNQ98*yJ7e`sZ;P@joN! ze{8IepVIFv+kcvI0RNuZtue=Jh4O!8FJ$!oY(YSm|9{c^NfzttZ$kw``1pT|e%$}| zD*BG1bvEyDXHu$91EGGn3Y_au!^NU&VIJr96O_cIvMa# zm8;#lt?o|X>Vq->p%B@zeCWsUgZBS(i_?=)v=_V&FRqAP0(R@({Q9OXugmJkT%CUi zFn{IZzAy?p6N~~g8j=$Ta|DWz~w*XQ#9s^%(e_THP9vBwF@OGlK@8WY7pyTh05|aU% z2B1-QET@zVWU#)|qn9tpyifW0-UiHf`fbYA?aOt?&rdM_^D(UOx0KK2Yv1d<>OX!n zD+vQOxPI&5#}C#R#-n=q--#bPGIn{3|M}`b(|hOOM9v?M5Bnk~LmwX}PaF!RALUE# zis5aOEfjk4w`t|=8*Y?DDbNDbO|D9A=|2~DHIZSfVc(;pzt!CRo8~PXWByXkkC(Ty zHq3YP@rPZ3*S;X2yT8eR|7f@TBQ=yE^8d|iF_)h|K57*qqs?{xOdd4fEaGe{%bU}( zR{9RtT05mmOgUit$c+w;SR9}}TV~)I(d{w}D@qS}x_l=F(1aWzDMejy+l%}5LvM0J z%Dj+2;Hos5_MO3o!&2kaiKR2%p6r6^5$b9DX{X$1gA^wHxch3k^SiTXC~{`^aTlIH zQ#pzcgPuAWXU~|+keDj}EUF+rw9t#BFS%*1AnL)@Bh>0OEUnwp5>2%oEl1d!v<{Z5fC3-L_;Fb5Q2Y_)+%sPy8Heeq%ulY%Tw?}lFa3fZ5L z(5%g7KnO4U)U_x2(*z1#86yi`TZH}MxtKbRm#iCWta*I*=XDzzTxi^k z12|b;f21k0KV3b^KJe2IX~OWVI?FXO99-pzUjz9J{B_0kcS^nRx2 zu_z%>3V8}6M0;ybCf3w!%9)h=6<#Xns(!dmNrAoWmCgSpPCWq+jq5kycJQxTH$E38 z_P49AIjO;Uwljd^HQTlPqw^z@4=E4))80BgD`D1Kn9E4iKA))cK~F*a6c<}l3ZoV4 zGXEWoH>`a;Af71+*IkuDEvJqez2Vj1(xCM$B%A7x@<7&nq%?M$l(}Woct0+U!s`a&{kX43>}Tb=l;BxSlCpjHoQpx}yAD@+`J+Al&t4>Ed&y z_zky@Bk=Z&We~y7i^B=aYC60{R7Z#J$RFsAs8%+b7A%Mi<{mC8EJSTM7b)&^QhXl& zG$>@;tKYocrJ4~yL)`6HXAn6GUN@|y^_naeM{vZ2vSPh@$t8QSp{(x&d3=0QXRtIu z+uF+N_zib8h4=#DZ9B=XrJNY%caXy_7t9gP&41me)dz=_&nTuNFuH0p^m09C?$T6o z<)0yVbTtrt>&QR6V0^0vBb@DKF$)Z0g)H+NbyTbut1x5bbtKz!h-1nuYh&^lo z$4LOg`b38q_&~6w^TJu|5*5SB$S_;7k}#nqw4*5zbQ0kTy}B&YDdf;To7I*sl+fx! zCb1_sqR;}Xxl#flt!yDGoCNoG$-xABMdrY)0Lq7q*eZKuR>)M|0;wW?D}Bw)CeG7< zSxsI*!79`wf`Ld>&7D1=F27Ho&XDS+&MrRKqTJy&84PaEt@MOlp1=Csyl8qIR7X~| z6@fmV-8u^*^M-T(yiRGD#)KAURMy-pZ#`(gTz1fBHpmEw56kyL8r>Yi+%EI0Ro$3= z;xH*m5))1pfZ73y-=hkXl4A*j&H!`~ZVz(v=_@LzV8QGc;*(?0-TrH1J@I|@i+t)i zQ|hb~*QSX8zxD2bozX!r9(ak*7*Xi`xC{GAu^qOvfvBW_l_L@|;zAF1zFRZcTB|8c zwokd_Kffo40AsvB`F#6C&2~yWL^?_dt&qT?7FT1fpoS@;8%Pcamx(ETQ?epIIW@f_r1e z>?@YGBH|VlNJ=QD9h5Rr39p*5O5IyD9OCj2=fJRqku6%htYZTfI#wTbn?Vi{;fS&G zuGDpUe6@(9pa|>s%V6^0u*G!ST9NgzELe-c>>n`LJe4$ zG?BH^@#Dg)PC{Fj<`>Q*3hK!+8S4z#^^?<|ew_zBmmhS;&Wl>GFSM|+U}po<1XL;o z+r0#v_=*pv6vi0Bi46E!M%QA*A?rvk&Qx#aaQPk&b4lY0QH-_aggstFCAvi!E3b>G z#QWmBq`E&%s#5yd3Kmw24ER=q#uE2lRfU~J&38k8wYVEZj!kH=G33%jxHSfPbr~p> z6d0fhtTWvQ18h7uV9YyyI01wfF!2$2HcOT2aU_Eu>W1Y`<5A52j{Gx4E&A|!CnCFu zmL%;ISDIG2AW*Tk$`O<+5I~yHLu#qD_ON(h<7k?MvIEv1u-!En){!ohbGPJIgTsNI zkH3{_^|Dj*5_z#S8Mlh}KRwImnWo;iFBm4z8@qWOGxBozWN81kX+xoYIcoeH8n9phpxnk|i(>oG4)L zH7|Dp%)+unm5AFqij#p+t>oSNlR zw^nyo4~kqVtk;F42TsQ<)++!8rh4~G>xWBxM5(jH@LwiRYu3uyuv_t(PY~6U-7rT7 z8u%fo#64&qWSLXyk6Sd%jdH=HVX0zf+xvb3>TgSTvCDY;sT+Ovm(z8gC|1{3nGsck z_R2!Ru6|77dvZYXYcjfZm6|>K(2W+MV+m99Y`CxF3f&RRmTHyf%cVyk>YIwjL|(v* zgSPFJh+7%+45C(hG|&h*By;oRxe~gr*;?A%2}U(DxBzhnU(2r9NM(Wx8t?Rq60sI- zn(#=)u#vQ|^!fAZsoL&_d}O|vRVK!u{YPXS$KuE_#Y~;shM`lGv$O&wQ7*P6`lH|2 zT4z(fF`OJcDvRK`B32~ZVTp{k4=TI^CqD{#CwO?`r-+JBuSFoJoLOxIM{FPh7A3EH z>I_Yj8xzI7)Et3JXC%5hs^7k3U{k3Ti9`$U$dgXkTWxFOmQjm-Ss~LlIr$`{01d`I zQVY3Soy?bA!b&R=VGao&fP^PJl`d(*`R+-l&T5eSq?Z^Q-Lxk{u9T!7fDh4C#uB4P zu5gwU1ITW%<`ADc&pnac;oK{)*0928`QuGqz4(o6OLv{GCYW(j1sH<(^;r%8-|m&D zUaD^y4(9bxAtLe6mU*1lxjkmgBU8coIya_Q?v*XW3<%it)=VwQMWB5tNsoX&0CX=T z`?3VvAKa_ok?&4(G3S`?s3GEGf)Nub)*NvK94*+HS{m12hIqe)g}N!5q5k2tm0|c0ePhgMA7cq@y88ksHp8oXHY@OfitkN(N6fe$G$#Z*MFk^wDTPWz73E2w z;6%boajt#*ineiSQ8}#SIzkHGn7#DVq@?fZA|JP*$!>ReGg(+yQyS8-Y%e@BUu=S{ z52FbY6^dM+ssWy%2nT{Ao5soBw-|~%5J1Uw7aP{sIbj>BDOP#m+y@0p#JKG!t!NHZ zbUvOZDGP8-=8FwuGdx5b@_F~U4CbV?PEQ6t2Ey;D8af`V_Ks>C5UigHu24l0Yw|Q_ zN{=~T_&Jw)Y35sOAr0 zAqoP^64NZ=2Q(P(I@JZSj6?F)Ul8XMKUNI1@__zXhOxF9>*RYFyVShcox&_1T@CXc z3geelX>YlXeU!)f$N?=*1;D6ZFMQuFQW%j-`? z#eM=6$e53SqDv!<#0sV~mt~7(Y?I zZTi-UGQ}r4vpXws8A~Y}ddyIRN;bm|Us0Xj7%!G|sdZ zEUia`bpcPt*1WuJsn@XFAKm#b@1IU;`v;8*b z7{(w%{|TWVa#g~IRj=;$;r`F7r`j8hvLp$-&z~7ihz$||Y5f~?J>KV>kF{Il>HPPV z_>zEgc*auGBhT$$fgYt|nlUyX9=`A)b$BzqxL4UvI+f-Qh%cK&Y}a!iE?B^d+Vhph zYQ1CwcHMkY!wwk}K#QktZGSIP{M#s8$S8- z;s0Z0!UAKaKo8PFYE&` zT{n9KaHG=RK)O_$JKvAOwme!|bC3R0fI#i)%m@9t0gj7hVvol-<$9bQxfHruHPy!x z&fc^PqOwKAlES;P4+Ia!r6e7u9xAD){sl2ANOv>*S^=7%Ugr`LtlqsOX*oot)etXp z_!)f#c=FET$(Qw1MT<7SX^?}l_hJSrPjgx;Wa4^Sx$B6q84dkWbOS=5yV>fkGN%?dV#j45xK`kaW^#8fuVJ?TrF z+{{_#rHGEk1`(@>)u_IZFCnJ9opUAZ$7KdiJ=DHzt9Vi+#ec|}Tu7R#WHYX}(zVAK zGQ3M@an@kH)hwha4;N_B1%5vE(%#u?L-vLJ%NHVT(wQS{)FY zSwC}%zzEkeMDF3pS!0n?bDf(cm02-VSZq|?Q!{@2J7NXedy;=DdNge*dTdOGqfj!k z5zSg@Mo&W(uauxn)o563^EY`5a3s@b8*GKC;q4->ygB56eJxmMUh187t0Tvdo|uBK zI@Rh z&e6d`Na@rK-pZA_0ccg&D+u(;%a(vKV3ZsQsfpmX4Fq@d^v;qmoI2T7ooLKn2=cTW zg+(H@)zNImq0`ORM@2o;2c04qD6D9M@+iP~mXqs5!}1kUxvmT`AEKe^fvq4W@o{1` zL%51iw$zaNr`ZQ3+BqH~W>{tHGB|#!wxo*PaF|UzZJe?PipWXs5k^l#qkTF?~{)g3!fUWun`C1x~Bob&Yhy zGHyo2r+77MQ_miQDjkFHBf>$cQwn`L)2%&AkV3x5z!`Nk5o}$-*yJ$E--4Z;!K#2k z7@MWoRRkCTucRHmUJIFSGK(XrC=vZZpVps=chg1KO7_BA%mlsWYME)Bh&zVxxv6`w z{T#PhZR$R0*&!_TC@ZZyn|K^_%&V_Yi*`n*PCo0R-ZtuW+A)JuDfDgEZ*F& zPoKR~htR(AB`@Xzu87FYitL^niWlvs!4e`1pyAzH(+$L$vy&?oENVfA3H13@RlVGL zo0~<1U=LBY9Y4D|uL2gsXXZ?O6nhFaKy=SruHIQh?)l0V3l?`U zNMKJ@;B`GG|1Gfrv%$XXp2&aV%>v5GmA1ZO$v13t+{*(%s$Or&R}> z=5s8*wqcu{fpi~o_1~;d6TX`_q8%POqs2!gyZ-2)^}y+>+afU9cOctfY>4lk@uzcq!?cYt9ZuJJAd|K0-^S>3 zd(O5FhvRoUYU!LeW9*|=z{*5bJ$0Dl$Q2o&J6U{kEEtyGnfbyiLOWV;-`3tR|-nbxq$~=%0LtIwAR4mOdKEKca z)C!kC(H3jnIv>3#u*DeaBG`tdfr0lJY_ac)>Rf1IT1C9Be6g845mL9c(r#Aq1Bx6c zJ)3XIjki;UkJG4y!NU>uK(tMT7d6Xrj)Qh-sn|W%;HK^u*KQ``i6G%|$`r-q`_UA2X*cd!);7%2;mq^gTG>QjeYpCummbzM`5maj@QXH@7I31x|;+7F=R; zAYwhKWx$FtbAI54ED#mORF73wj!*K>?~ab8thA@lW2$I?;Vm@XWrZJ|06g$!kx~S3 z*3?kfv4w0G?o89qMg=2t-E!yGsOj^#K$0*mJ}@ZiLYUXw&~rIXRPBk$d;SRi<?c9oJAw^Of9N3yA;K$LX|6uBi>> z@!T^#d5)Gi6T5in&02bQp6N#yy^0v^5HJfM2j@>vS9op5j`_T-EV9rvUvU${&;@?& zh+bsHu7yy(*^2e=o=}mmgp^#594FRhJE4Wven~9!MGBU1U{Z)Kd~3TOOben`QOoHH zEm*P|FN*BgBF__E@3#7gC4G5~qF1M#Gl}_p-l|?S%+?()C|0~MCnjBNTCkqE`T;lQ zovtt}&xGFsJbseR>Z1%A7$y}F4A+vl1_8)ZbLX5loxTcrbtat7p@|q7x^ul;d@pls zh{%W{cgn}CXwx?jr^W0-AX3*1`0&2x(-j6deqAbTWP$5k1;R^mRf>*sdp=9L6@+l~ z0ddtH24x^BLFpbb&*pB*uTtlX-3RqXzBLT0y%dBbD7Q4H(S*9Hc>oG~ z&!xO>M0=f?l0XF}PoUrM=W<@jIgQYEq+wDdDRElF(WbMf!B(@}GO4RJlI!%YU}5XC zSb230^Y}CYM1EKRa*VCfp>8uPvLw_TMKu&jwNscOrOu-rCJBdno3pjPW9+Wj`7${b zc|cRjkNL&(-&<>pejg(yBQ$vx4d`~+chm?h<66CK9YwCzw|LtML!YZyzy-MAIW&{C zw?rbqei|U#i1O~)$-rq8HWi8#&~PZ98Y*eU&g_E}Ai42rfZ9M67;HXNv`(r4LI7GV z-M(d&i26E@dN(>t#(aeVDj{(e$Wsrwdb;}8q0&y$4 zAX#cDy4g#9oz`9rP830gxWWR*qf^6XnW7irKVj&~Lg8&$KD|TyeISGpv*+1RJBtKS zvJMvsfFqRWrCUp%syA#-+`6bSsSu?EP9=4sMc~-Z-E8{kK7ZELPNx$)Neu3*oq?^& zSeiVnrQ z`Ha`ZF2&V#_|w3(BfFcNZv6t~Gsec}ZG+byI+=uQ2OQJpjbf z8zPu7Ho?ntU#}L4GyGE6yY}WCsAX>-m*!(vA4r27BP{d*S&>{Q5|-{!hrlZl)g;D! zjj#vZO9pGZ9HYst?RUj>hahX5S88#J#rH@mFw0TUzUzG=)D)WIqaOAJ$aJvR&H9cB zc+>-n?~}0CDT1h#`y(MBRoF;Yx0vy zE=dy>&_Ad?uAAZZaNObU#7Fd(ipUxW>aT$ezFSIivr6eI<~0Q~f0=q;dZ&P>qf8 zVB`6QpG$!YThIj$?wh-_hc?Ge#r=!Wn1xvA{C$mczFJty?+wtVC?Ko$50K{fALjq} zul+%*A-o6vDHk&wSGOMwQWMqHIJWa(J=yXlF9)lQo=6LJSd2~;{CsygSqeD8L2tp- z#{I8v7-k?=N8_F>L7-js`lQ$#Le?vmzaNMl9G|uQJ+EccD_J~UG0OQ6=_=Z7x_wj3 zK}>TN!s1 zzO4`hBHz!gy3#V6_Z>$q%Xj{tG}lEeXxhN=(0QDway^nsWyvhgzfJcsevt$y-osT||B z_k?pksh&=~IJOTueqmC|tB;QnNhq`NBIurBO1j`60xR!K_&YqGZ`$WE5E`X5C-CLc z1ZDTg$Ap4e(1@MxnRQ8EkM}1Hp3byc0~R6HNM@0(0r^&RnIx?hq6me`CbU}r1QQk}wR zweNIEk)%&0ia0hheA&iw_(ePl<8P{7j6gu?9y(>Rt<7>1)gm;P>S2~niKe)%45_*8y3Tm8UfPp;fNxT&Q1p<JB1Xv0mk*R56FiaDaHrjgDa0^wa3`eXQWBxlHVeEVu{xd4yzqRs^bi3qs4W zVu*O9NK?grb-iV7qNHB-){;pdTkGUIgdj*o2p%e~6H7x>Zr4eruPgv3p{Tf}M8EkQ ztrro>-%AEl{x*l>Kv!#<>zT-MY=P2^`)w|on>2}|R6YR#fs9at zzY?9n2cP{Yhm^ncf5?WbHT$oCygCYYjYnekQ40qTB0A%(!(1&DA&w8Ww#L9^Wq<*y1?7B{r7OsaCU6MNM>bWKz5`!6sNSJ?DVHqM zuU!hTN~K+X^O`C`@D-T9AuF~0mlgYCP4niDvoD@$pSJQzuYQ*246Zh!aW1UR6tBoL z@lCnD5Uo1@RN3*4-IK7{yoN^pr+?`$_peB*-=>`>`x%e4c6keJk9-SmV>w8k4N3YI zmVqxZtaT1L1AAL?zX~sF@7QbG_GBfjZ746ho)8{+_?Xc5Relz`GD6x<=4p18#p|vY&tYb-6Tnqq~H^tSD5E^pXdDmrtONhZ?Q%LE(;zjxM9l zN*g(;;iy76q-tlJF1asM%83yt39 z5(<6;G&Y6p)U9IEh58?|@GFp9vY)S4^}PnLd2TF>od0 z=w(k>&i&n|dvAt52m4NtN5W7y-6^3dSwFIRZ%%B-fpe=u?Dh(0OhsaRItTqkJrXT&GWfuOLus*pC)|~Fk%RRs}U>$9uAoneNrC(o;wC7 zeSnWZXMY5}d$h&$s+;e7+Sv8IuL8GtFeXEKwFBVd_uzFMYE+4ish@4h*4HG}Ct-Ds za{}VS+w7x_#eP*d^WDT-g$r*(aQL+TQH7Em0-?;cSr@B0Z=hyYMv@DcN z$xXf*A4v1YMf)DVpVoQ|L2=z{$5v!;d?xVQ?yJ|?6sUIS)}l~ESux(c2f~!9jX4sDMA%8p9l9L&A5a0^Zy` zum*~BA+|M2*D^~Ec#@qwM|o5ZN5oyMmBKU6+8G`hr7r()2}&R8$RyJb{-{Y!%MC{; zrmU-U0@65{83!Tm?y!KZmj@P_i7s`|QtabAVVxgWc7V_Zns1xU^G*24K<*8yfUA&y z9QrJJ(0s7LmD0a)FI}!E(Kzz}?_S#bICU=JtBf0{?!|-`c|ASpO-)qV6L{^Z(brj; zZV@B5!+3J98B8l*aiKw-<0(b5f4w&}Mqlk!oQcua@#`A)s zb=cASd;3|hA}E~&(SoC;nLjmh@R1Wiu0N!{zJ|!(uV37~u5S0!VsLHS zU9qirr?JNI&0mK_45I68PTyEY(EmmM*=67=Xg zx2BJv(S_|a|5e|D&P5l~vdxciKbU>P8VUF%39SiwH1k2JPqv3c)JFl5=Hgn4FWA#0 zfA#%|q8Pqyjb8VMEJcrc^OV0@FGQmrOlvA_7uG+^{zy!+yR4VVC!V`<%5^*ctw}{T zB@G+ysi+>74toG+&GuEGK6#B@tM&Ur*yi2+ZiUutdoy$A^I5}>h$J1=kxN~A7Qd)H z46h|d3Fn%x75rdicWE%w^!%viO2`hf3k?3{88+bzUzGEG(|g71I`LjIW?s$%{?SgL zN?8MA~?-#;kDCW`#379H5sYV_@npBJ0TRm zi@!fI#<7{>|8~TqsH4h0Lwt&k;G2EoiUT^*mNzOuqDV~p7mI@Kfd{Wy;AcC-9k@qL zct^iI=cAoX17`C=32ytF$;WJy^+5~R$CR_-hfCfOS{sFF&dsD2ST^0#Ibrd~PpAF* zudYd-s`^ap%C#Vz^vhyIIOg-Et-E2%Jl@ZL{+N2c%$Kpv)aLUsEO~{`ADT_9e|iwT z>}~ubW%A$@CT7ETFC-!aHM!SU0*i1MIO?S->D+c~M+`N)oJiMma25JmA=dZ}dcy)z zA@6cY?V+m8g=+))}(wm*(Lo9q~1B zfFa3BX(&-?i|KOIGG-w4f7@Jzez-ay+_AMbdjS~D;EdfUuCm1I*=x5}5%v1bCI2`O{^TBfd7wkltw?jxV=2oVAyuH4X>@m#G}URH912={FZWa z+QSz2jB?*<$&&oj9M6agM1G$CK?#@-s()st|Eu8MvtHS;U2yeiRob`WjD;^1nP`W2 zd)nGv>p_cUHJHF~eT%lr{4&_bVnbOp7-98{*;Z!4zjSSbbE&W1nYLHKU7nQFTLo zwO+mwloz_(Q&5!*+6g+wRF%b>DKAdz$NHHD$p!I0qm5E5Z! z)6jaNy5eb5hC6POjc-^yV*2fw=KH@K%^od^q!;`39z6>ryz2~-9Z!Gr{BX5GU|u1Q zp4{ks?Vb-g>V~oVNjE+EerfyLN@=i15!m7GcAQdNV;T7@)Mr9`XS&i)a3|7t;HYzA zsZ?Z6kb-$5qd86@$SQ_pCI;B)l-~96q!;@<2CfWhLckpD{~l3RF=L{dmoIwu5lHGu?{$M6$1119FX<19M8^ZC;04V zH9}Ql)BwWgv#RDkuzL=AP|VO(gg!E}kEpRTWp4;K0PUyen@zp#6t`FyT31R?OWz&{ z{EA^)*FH>!Y1#}Yz%B;_cZgc@#tRm!08bO9=tomXr=QAQT8DhikYsy~Hy#&iwM_NhKhf9L->A^=e&8#8F}Tc< zWY%T3f!Y4E?bQT6e6hry?alpEhf7K?R78`6tYpJ!lv z>QcAw{V)_9=3o?Z6h~_YmuIYNgp)iK>hQx}XEG%Dp!EmVy+@MmpRjJUM%j$aP% z#j(#9MwYE`Yv=pE6N!MnMYWX0`n)9~rD&@$3$Yqe6f9k|ppVbQCwSn-}ZU>tJNOA9WtY#+f8c1tJBFr7!W*e z*yv)58_>cOt3_`jt_9V7kJ+I5^85{!eah(EMl!j{ogCx5@(C#;CUN?%tH=EY7jKOr&h>oDvhi(fC$c@ zqVg3;ptHUb8_JKh6N2MB z2B*#>Hk0neHA{(a3oTex#u-^aH)Ps=qGYH?FrwQBqSM_huVaBq=RzzS+bmEpj>s zkGrfm=I(5v{$3)rej!X88OXUj%UUijpGiacZLpqEpE)tAJ6_!YEe!Xj7Xg?@<~v#1 zWd%EhUpo%?#nyPWaA+Q&S4iSQENIuP$7mBL^mP>3$HR&kg0fH|)X3EUSjzxuxY!~r zC7@r}5#%>P3L}O1A%kL-h+IB!Z3u}49rLRT0CMx5gYg8Qd-S1pBTi=)9$}_)fuKSP zEjr-i(ygpS>edi$8o=Lw)8!hY-|j+ViRrTPFIXcnTe2aF()7F2j>&_mrFM!D`}I(_ z+mWVTF<7pPPwe`8dC>L@cxtFuPk1ca4)W=M}0i+tPxTwvT zk9_lHy&1mMgP&y=P)F8{I4k9|TBv_;C{%ct|Co;F7HIZT{**Wum%@&R?96@rih^=6 z_jdoAP=*_p%6b6EPvUp}iEO!V*mPQ#xm;R@#4P9k-*D}J1H!T=LLZa4FiCqz478f8 z{R3y`Cv7>OMr4IPd6!few)?xAO5Nzbuvg^+-~Amu&q>(D14@vr z$yqU171T&%4TRA)=dl+Ka+n^bpQY(gQ7<#_9=jLKLQRZ`K_^-i7PGI1oRs}?e6>Nd z{OfR{bJWZJN*j%AYlv$UhJT`X19Di}(O*#)d zJc?BAZ#KjB=6a^?2mq{+O*~7IPRAKBA-CO{$_;v@Ir3c8O&fFIle-h}^2TcLWv@?D zbnW#sgJ}P#4?gs#U1H?r5OEEK^G|Fbv_zwK_xxfVnKHl(b&$n3(7D`(qQtFcVsT&> zV^EWlKwt@JJM&jEJhHbMN09hAnt!Ma(IzlpA5R@!?{aId1Hkk(zHQ%q+xvK(9H75hLhT_Axf^#&5f7S)BmYB z?|{SJANzBXSkLBDF~PkC6M%t`=Y+_p)S59<=q}*!IXX+AC?yh z&}Fs}WL-`BIoSvT;-YgmTvz$Qz#bM)S7%U_u(}@drmGh<9gnudHE&T!nvS6^)=Pyt z;k^cJ9yuBsZ$bF;AD})W)B9%Do2wcnLw+};U8|)H$-t(Q#e!~=!ssVx@X>&M4mO_X zTvqmyMB--^pI6+BX=2n|@!$pTz^4!rQ8k z%P;6%HQ##RtD_}3c^yI)MXRE8NF`W99~d;r4Mtf$7^?utMIXQ2)9Od47Z5hTooB>@ z4t^9U%H2o5$D5c%4(r`5@k>4T4He@`+iPUf#L&&Z#Y+xl>?| zn|B=6{GspD;<0US;6wamK`P{XVaa@k4k>BDgojC+5mZ#a?n%pEC21vmSm?b@Tyop& zVTP}kvY;j8T^O9bJ!n+!u_}$9dk{B=d@Ho&W7u+V`p`otQlheKbI>-shN82N5zyHG8d^|YfOmA9&(<7@$iELm*@0rwY=M^3`$6}qHp+Im3K_XgsoG2Q-dyzXRiD;l4#4e zDj}dKV-mF-n3+iMWkc@*%|HFbufFy_hI)77P5IG>l7EWg?psZZS}AAxHJDN|v#zY4 zFMYw=%rpBYVm6)^(O?lbZF0w<$ukPfl8%Cwwj6RZ2-TmE@;g<`GNF721hm>Bt~r52 z(?cXUy55&6b#Qkv_iX~fwtt7=0K&zV-Kl=g0cr5<$06+%zQfu|IN%fhihMxl$Ybd+ zwKK8YH^vELSX-PDvO=9B^Tku3i^ZJ%N9uHy+Etlu*Xfd~0F-ph_*%Nnvf{=?D5m$6 zCPOH@B1vj756iJ3@FZaToCdsHx#3%So7CvN*;h%xQUkPq`)7h1X(5YhrYc@beigNz zq#X?wrT08HV@dB&$+1sM_cAm^M@4mC3ksPk5ALfxlIeGZy{!}9SmKMi45YoQS4p9a zr9HM%niqUzmzUm=3Vz*+)@>mlzRS>^VhYXCj~UYqM9k@}$D-*?7yT%HCSk+cDoSf- z;?!|>$9piV^H+5|V7w)*!NKF@gf3(dv@1Xrdf|nCGEU49G`3#0#}Dbv^hbL$r3u&z zEhnuoBVY`U^=18>#DB=mXZ&JjEiPnM`q1)rfY12=ZKYoa@9`5l=|4Z?d+jA?*o_;F&$ zg=Yzj8Io9mbiFFwtacL}@r4@3kzfM>uN=zU^XK9BSe;`0iWbV|3oe7Z2i@e5=C%EH z(z8To4sN{wYZE~&4U{nFl`wCIxz3E55aSv$wjk~A0^MXeQ@1KM|%m)|r-pDjES(iY^xMwLb7wtMj$A)RiZQe3q&GkGWwOD5Igd zgmcoawIF`B{F;A)8yeS4L|QMnj5fzI{-R0zXby5sGV4QU&FMP9l6IER9Lr{02LF-h zzUDU3oj=xm2Jo><;!D?^cZ9c}k&fxY_odJs~@0wcH`xk|*x9H#hhz1wb-#uTHS;g|h>U->&k_NO>QBGop#Do%Gz1NeD4;4I!OtRH^nFc+bysaLl7+mL&xmu6PT~_I% zD3&Nu9`hGChRqwg(NJ__Br&OJ0657AGAvt3ZayxTNKE!RMi27t0a!H3Cc2Lca~}xi z_6z(zW&xsf0`O@#HxPEjX|X=&?zu3Dt&O;Ko&zG8vE4Va$ibvOL=1s>t>$REX#gjP z2F%y;_Z<)Z{a9Pdyw@Ko$O-LCwlG`lq!p38(Wqj(J8);^ZtR)P4OFXdKprH^8<^7c zcpagHbMz#G4J(TzJJyb^DtN@XRX}R@ZKbZ?eLWe`xRR?>biC6}r)4TsrX?OPx1_T4 zfUZP2QSr{;bq6ZswT`%C-<{oeO2Rj`B@^eHOE(|B2%2fR1Bkva3KR9+w%j)!USWsl zNZet85w_wu?@8AWiSRCsPCH$3`;2OS{Gdj6y8Kkz?YkwP?&$Xo+)g~PiLW>j~-P{gE;UuUo$hIO)YR3xOEb4pdw(Fpmr zf~?sP<32|Tqyb4=&(Km~PU3tGy#76Yx+}+r5wi+b0%(b?kQl;_aAAgl4>p;v^EWHs zdJ$eKu0i#7=N#;E=Z-u{q}uVSL8d-U^2NmtQ*h-hIwz^{*<;5;h=}911<3mmQQlYq zEFm&Qt*wll2v)lQT0iqBWPG-gih$93%N!f&E%&)+6Ow2bLZE0bO=h)JXDS;o#nZ0O?F z;B*n|1!IDb`3M@%blXeFMP?(T3qJ%?m-|?U(P78@;{9|n)rr1^@9k!SG(gl`LHhy4 zWuh$n&);eME__+gO1be^Es)cl-JGqS#-|L^J^L_(ky=mv7vzuyt$zoc5^}^Gc5QDP zJ9M3TnF4lra(-iVVNm^0BkNj3_o<#j!j2TnCv?cPnX9sBJ3d=Ah%bFs;d+O+QdU&; zFtDi#MbLK2(sB*b91^YVPOYKxuS~}HCV3Y zBOqXxf@%?QU7S!2NAhtA8|D2sb(9gQjw974HIQ$E1~k_O>CpD|3$-yI0RB4`rZktOX<7#Da#e(5b!f@PW6?wnG`)0d=+q)Mzq6VocBZ0E~EIV&q_ z$M6bCZ;MtrsKxb`J*3=uv<0Hth!v-Wv^zge{y{ja*#{=f;Y}XtH$jR73p<%m3-;SU z8_jcd%v)zGR$(%sivRH1#Rp=Br?JVYkfWCt;#ZVUGnHMIZorK$ehuU3dyx{w*YtJe z!fAD3O%MkF`leT@g&5zLCDyQ$)NZ6gjjYU9vBt z8KgA<#tY_4cOui2?JhC;Fj`^s7V#3)l9AGWk4W6Q#f(mUT=|aSRYo)_;{Ohg(zq~1rCkvsi^_=^NVMOFUD9-?LFYx{*;GQ z;lhR(U-W9#1S;0-bgt5O0`Zde&e3A3vardt$MaQ}sJn=6&UGhgkg+yio->w>4(ip1 zFmL~A(Wig}XB0{r6j$Y;|5BN^J zl2ba?xW99?Jdj=-nZKV5nmf#6J8J>)fz02;!_S95|Xwne5PZ4w0r@6!)xy?9V>yS z7fD@+q^YjOGk|utG#oxR=&dx_-YScBFHLOYM)pnjT(#H04x%v6m^62@vRL+~{_#aC zN47?FcdW?Q&4hqE|FIBu8Zo({R4N5X(}~kQ_24gpyR_fKJK>|-n}{gGz&c}--+H#B zbXh5i`tCI#s3iX9y^ZK>gIEd*$f}5MT^?SOZU0k+y*+{qcJ$O&UxrN0sWVhod z=rut)G?jg>mYw3y=vTU%6U%V@dDD)u-bTfb=BI0!x&^l4Uv|rziXDDWvLPKn=�P z$1>QR&^abSi*y6Cl3fAm#cZdJ+^tPG)j@^8(As;A>bRV*c>i;f=fg{GEJr9N&MYFI zwLG;;#FVi;H3F_TvHH&@uKpb4kj3jV{mhevfqM1SiqeB7;{D7=_=9oY#d*fzEV&DA z5AUp)vIX}kXv^tq!J@LRj9#y8cM${CSxT$uPUc0f@9Vo^AL!q-*&_m)1mDgi`ZgC8 zJ2=HFE(Sks&S*>7Be7qy-5Plw6?2y%7FBQsR_@sD`tpLSoBoMDDoHi`l3}>?OwFMv z&oFFPu3}0rd^Qg?0!d5HO$b-GByqo`lT*)e;I5N8tgPfGW2-t7Ssu^%{xY-d4Z*}g zVf?y-sENf=L1|&oVx^(ZeB1qtr3uJXj(o(l%N2UfPYY+lo}AUZpI|`-6hlwHMHAlr z95p7~-(P9YL0bw!?o zIzV#+fWN+)`2UcIf8J1k9Q@N;|2TG({XZ{2=507-GM&&r-G|(we^4J-HMIG=5@+oR z2fg6c%vkD!=}7f4=n3Voc2@;J&pAQZUj>UDvoOkGoNtzT(6Kw5q$FUJUWK&2gp(}7 zO4TLbRB)Nj1ua|(Nb6JkPqnnplDXp5{(B}h`eMnxO61df6n0;tv-?Zi*iRZ`+huF% z|IP|p54e9_bJPRdC4NV&CO^kAjGE$!Ki~OiQh{MUhB(z8nAY3%aoc}G%m>dqa#mCx?FyuxEqG1v-e+b6u)s)6GY8` z>wAmwg;X)d(g&)H`Y`W101GfavOB)CkjA&?XI@ zD+BmNxG%$b92`tiuOe#zJhrx&YQC$tHNuCi{UT@zaA)y%ZjcdSl-uAs?PiO6E*ZX< zruJNCB6n2*t;R&1C;}GT& z{i|qiu7&H%AmU+ZJ$=`mBB`UwIGhG7)yUf%_bsASYJ%zqJFzAm=|Cw#L>L}Sc8A!@ z4%jIaNU3@7HOS7XS&nz{PuX}qgt`TJYZ9$qtf=FB;}$Ei+}(wbJ0?f{^q(e~YAls* z&CmSG->h&b*=up(LrIqV)_Rhs%#`cr5sA*yzGd7!MUkCS4+CL!`lp{G3VV*a%LG|D zz%9qWdc3b3mIGIBdkeb|NhPvx44x!VYU8GcihezyWZToF4tK+o6MvL?)QD^zJ`=%h z8DedT5yT`B2j)?N_{1&8<7t+ga>de zF~sDx)Z(r2;}jXq98A!;kSl&|B;uw5+7_Jc1wA<0MRLyo=DYF zDD~DqeIkmk!Mx->k}mfG+0L-+3tY?oWz;uu;f~}Bn>a!&;rn=%lUL&9`0$|zvYXjg zpL3Zw=$9M)^;s@rI*dT<$UF%XwmHziH@rMdD_75&AMUJkm+>%@(9o zdmBNji`~d4Jg?|j@k*N0iL{#se5AtW-9$9&v{cXmzkJKzE7JX-y%28F%Np~*?eJ9( z73rezkzT0fuS#{<6N16p#TM%7P$Xk1?Io?1uiSc%iyiTNC%KCvJO=;uMl*}SVAT-X z_?w$4FKHd(© building model. - -### OpenStudio-HPXML Defaults - -### 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 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 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. - -### ResStock Samples - -TODO. diff --git a/workflows/residential_workflows/building_inputs.md b/workflows/residential_workflows/building_inputs.md new file mode 100644 index 00000000..129e5c63 --- /dev/null +++ b/workflows/residential_workflows/building_inputs.md @@ -0,0 +1,121 @@ +--- +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, a number of inputs are defaulted using the OpenStudio-HPXML workflow. +Optionally, input values may then be further refined using either a customizable template or samples from the [ResStock](https://github.com/NREL/resstock) 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 a [GeoJSON Schema](building_types#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 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` + +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.) +* HVAC systems (heating/cooling 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 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 v1.0.0, optional boolean and path fields may be set in GeoJSON features to indicate assignment of argument values corresponding to ResStock dwelling unit samples. +See a [GeoJSON Schema](building_types#geojson-schema) optional fields section for specific boolean and path field names. +The path field should be a relative path that references a sampled ResStock "buildstock CSV file". +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 a number of 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 and [ResStockArguments](https://github.com/NREL/resstock/tree/develop/measures/ResStockArguments) OpenStudio measure. +Each row of the buildstock CSV file, therefore, becomes a representative building model created from mapped model input values. +The general OpenStudio-HPXML/ResStock workflow is depicted in the flow chart below. + +![os-hpxml-resstock-workflow](../../doc_files/os-hpxml-resstock-workflow.png) + +URBANopt connects to ResStock by matching buildstock CSV file sample row(s) to GeoJSON feature properties (e.g., building type, number of stories, floor area). +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 (e.g., 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. + +ResStock samples are defined at the individual dwelling unit level. +Therefore, with the exception of stochastic 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/foundation type, orientation (e.g., North, South), location (e.g., corner unit, top unit) relative the entire building. + +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/occupancy.md b/workflows/residential_workflows/building_occupancy.md similarity index 83% rename from workflows/residential_workflows/occupancy.md rename to workflows/residential_workflows/building_occupancy.md index 7eb51636..69af5559 100644 --- a/workflows/residential_workflows/occupancy.md +++ b/workflows/residential_workflows/building_occupancy.md @@ -1,21 +1,21 @@ --- layout: default -title: Occupancy +title: Building Occupancy parent: Residential Workflows grand_parent: Workflows nav_order: 3 --- -## Occupancy +## Building Occupancy -- [Schedules](#schedules) -- [Calculation Type](#calculation-type) +The user has control over both occupant-related schedule types and occupancy calculation types: -The user has control over both occupant-related schedule types and the occupancy calculation type. +- [Schedule Types](#schedule-types) +- [Calculation Types](#calculation-types) -### Schedules +### Schedule Types -Occupant-related schedules can be either defaulted or stochastically generated, and may vary either building-to-building or unit-to-unit. +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. @@ -26,7 +26,7 @@ The seed is determined by the index of a given feature relative to all features 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 +### Calculation Types Occupancy-based loads (i.e., plug loads, appliances, hot water, etc.) can be calculated through either: diff --git a/workflows/residential_workflows/building_types.md b/workflows/residential_workflows/building_types.md index c574a43a..70c575d1 100644 --- a/workflows/residential_workflows/building_types.md +++ b/workflows/residential_workflows/building_types.md @@ -16,7 +16,7 @@ Currently, the following residential building types are supported: - [Single-Family Attached](#single-family-attached) - [Low-Rise Multifamily](#low-rise-multifamily)[^1] -Only the *Baseline* and *High Efficiency* Scenarios are supported at this time; any additional mappers will need to be updated manually. +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. @@ -38,14 +38,13 @@ 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. +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](other_assumptions.md) 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) - #### 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. @@ -55,7 +54,6 @@ An example geometry rendering for a translated HPXML file is given below. - 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. - #### 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: @@ -82,8 +80,11 @@ Optional fields: | 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. | +| 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) | An example "Single-Family Detached" building feature snippet is shown below. @@ -131,14 +132,13 @@ You can see outside boundary conditions of "Outdoors" on one facade, and "Adiaba ![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. +Note that the footprint of the modeled unit is always rectangular even though the GeoJSON footprint may not be. See [Other Assumptions](other_assumptions.md) 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. @@ -147,7 +147,6 @@ These OSM models are merged into a single OSM model, as shown below. - 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: @@ -174,8 +173,11 @@ 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 | | -| template | string | | See [Customizable Template](residential_workflows#customizable-template) | | hpxml_directory | string | | Relative to xml_building. Most required fields are then optional. | +| template | string | | See [Customizable Template](argument_values.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) | An example "Single-Family Attached" building feature snippet is shown below. @@ -223,14 +225,13 @@ You can see outside boundary conditions of "Outdoors" on the roof and one facade ![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. +Note that the footprint of the modeled unit is always rectangular even though the GeoJSON footprint may not be. See [Other Assumptions](other_assumptions.md) 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. @@ -239,7 +240,6 @@ These OSM models are merged into a single OSM model, as shown below. - 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: @@ -267,8 +267,11 @@ Optional fields: | 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. | +| template | string | | See [Customizable Template](argument_values.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) | An example "Low-Rise Multifamily" building feature snippet is shown below. diff --git a/workflows/residential_workflows/other_assumptions.md b/workflows/residential_workflows/other_assumptions.md index ce6f49d3..858052fd 100644 --- a/workflows/residential_workflows/other_assumptions.md +++ b/workflows/residential_workflows/other_assumptions.md @@ -8,6 +8,8 @@ nav_order: 4 ## Other Assumptions +Other assumptions are made for the following categories: + - [Geometry](#geometry) - [Fuel Types](#fuel-types) diff --git a/workflows/residential_workflows/residential_workflows.md b/workflows/residential_workflows/residential_workflows.md index 5bdaa0d4..e55b2dab 100644 --- a/workflows/residential_workflows/residential_workflows.md +++ b/workflows/residential_workflows/residential_workflows.md @@ -9,15 +9,18 @@ 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 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. +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. -- [Building Types](building_types.md) lists the supported building types and details for each. -- [Arguments](arguments.md) describes various paths for assignment argument values to GeoJSON features. -- [Occupancy](occupancy.md) includes information about schedule and calculation types. -- [Other Assumptions](other_assumptions.md) describes modeling assumptions for geometry and fuel types. +The following sections describe the types of buildings supported by this workflow and how input values are assigned to various arguments. + +- [Building Types](building_types.md) lists the supported residential building types, including modeling notes and GeoJSON schema details. +- [Building Inputs](building_inputs.md) describes various paths for assigning building input values for GeoJSON features. +- [Building Occupancy](building_occupancy.md) includes information about schedule and calculation types. +- [Other Assumptions](other_assumptions.md) describes modeling assumptions related to geometry and fuel types. From 16708f3f0d6b24c1e5903e7084e296e7d99427e0 Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Thu, 7 Mar 2024 12:38:51 -0700 Subject: [PATCH 24/37] Some more fine tuning. --- .../residential_workflows/building_inputs.md | 43 +++++++++++-------- .../residential_workflows.md | 2 +- 2 files changed, 25 insertions(+), 20 deletions(-) diff --git a/workflows/residential_workflows/building_inputs.md b/workflows/residential_workflows/building_inputs.md index 129e5c63..642eb7e6 100644 --- a/workflows/residential_workflows/building_inputs.md +++ b/workflows/residential_workflows/building_inputs.md @@ -12,7 +12,7 @@ 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, a number of inputs are defaulted using the OpenStudio-HPXML workflow. -Optionally, input values may then be further refined using either a customizable template or samples from the [ResStock](https://github.com/NREL/resstock) workflow. +Optionally, input values may then be further refined/adjusted using either a customizable template or samples from the [ResStock](https://github.com/NREL/resstock) workflow. - [Default Values](#default-values) - [Customizable Template](#customizable-template) @@ -50,24 +50,24 @@ Customizable template enumerations that are applicable to residential buildings: 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 +- 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.) -* HVAC systems (heating/cooling types, efficiencies, etc.) -* appliances (refrigerator, clothes washer, etc.) -* mechanical ventilation -* water heating +- enclosure (insulation levels, air leakage, etc.) +- HVAC systems (heating/cooling 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. @@ -94,7 +94,7 @@ Users should ensure that specific assumptions in their templates are accurate fo As of v1.0.0, optional boolean and path fields may be set in GeoJSON features to indicate assignment of argument values corresponding to ResStock dwelling unit samples. See a [GeoJSON Schema](building_types#geojson-schema) optional fields section for specific boolean and path field names. -The path field should be a relative path that references a sampled ResStock "buildstock CSV file". +The path field should be a relative file path that references a sampled ResStock "buildstock CSV file". 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 a number of individual dwelling units within the actual housing stock. @@ -114,8 +114,13 @@ In the case of the air leakage infiltration rate example from above, ResStock ex 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. ResStock samples are defined at the individual dwelling unit level. -Therefore, with the exception of stochastic 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/foundation type, orientation (e.g., North, South), location (e.g., corner unit, top unit) relative the entire building. +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/residential_workflows.md b/workflows/residential_workflows/residential_workflows.md index e55b2dab..93c551d0 100644 --- a/workflows/residential_workflows/residential_workflows.md +++ b/workflows/residential_workflows/residential_workflows.md @@ -21,6 +21,6 @@ In the case of a multifamily building one HPXML file is built containing multipl The following sections describe the types of buildings supported by this workflow and how input values are assigned to various arguments. - [Building Types](building_types.md) lists the supported residential building types, including modeling notes and GeoJSON schema details. -- [Building Inputs](building_inputs.md) describes various paths for assigning building input values for GeoJSON features. +- [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 Assumptions](other_assumptions.md) describes modeling assumptions related to geometry and fuel types. From 6a7a74cb8eb9b50fb5d2a12968d781be14cac6a6 Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Thu, 7 Mar 2024 12:44:47 -0700 Subject: [PATCH 25/37] Even more. --- workflows/residential_workflows/building_inputs.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/workflows/residential_workflows/building_inputs.md b/workflows/residential_workflows/building_inputs.md index 642eb7e6..67d6362a 100644 --- a/workflows/residential_workflows/building_inputs.md +++ b/workflows/residential_workflows/building_inputs.md @@ -97,7 +97,7 @@ See a [GeoJSON Schema](building_types#geojson-schema) optional fields section fo The path field should be a relative file path that references a sampled ResStock "buildstock CSV file". 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 a number of individual dwelling units within the actual housing stock. +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 and [ResStockArguments](https://github.com/NREL/resstock/tree/develop/measures/ResStockArguments) OpenStudio measure. Each row of the buildstock CSV file, therefore, becomes a representative building model created from mapped model input values. @@ -107,7 +107,8 @@ The general OpenStudio-HPXML/ResStock workflow is depicted in the flow chart bel URBANopt connects to ResStock by matching buildstock CSV file sample row(s) to GeoJSON feature properties (e.g., building type, number of stories, floor area). 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 (e.g., the "County" parameter maps various weather-related arguments but location is already defined in the GeoJSON file). +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. From 74c79d90a5e190233ba7124837a5a909d852f31c Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Mon, 11 Mar 2024 09:43:43 -0700 Subject: [PATCH 26/37] More minor updates to building inputs page. --- .../residential_workflows/building_inputs.md | 32 ++++++++----------- 1 file changed, 13 insertions(+), 19 deletions(-) diff --git a/workflows/residential_workflows/building_inputs.md b/workflows/residential_workflows/building_inputs.md index 67d6362a..40258011 100644 --- a/workflows/residential_workflows/building_inputs.md +++ b/workflows/residential_workflows/building_inputs.md @@ -11,8 +11,8 @@ nav_order: 2 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, a number of inputs are defaulted using the OpenStudio-HPXML workflow. -Optionally, input values may then be further refined/adjusted using either a customizable template or samples from the [ResStock](https://github.com/NREL/resstock) workflow. +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://github.com/NREL/resstock) workflow. - [Default Values](#default-values) - [Customizable Template](#customizable-template) @@ -34,19 +34,13 @@ The air leakage infiltration rate of the building may be changed from its defaul An optional template enumeration may be specified for each feature in the GeoJSON file. See a [GeoJSON Schema](building_types#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. +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 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` +- `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): @@ -64,7 +58,7 @@ The various arguments that may be assigned input values use mappings contained i 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.) +- heating/cooling systems (types, efficiencies, etc.) - appliances (refrigerator, clothes washer, etc.) - mechanical ventilation - water heating @@ -76,18 +70,18 @@ Note that not all possible assumptions have been aligned with IECC requirements 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 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 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. +- 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. +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 From 705c2acd0e91e72ef13b272211f21aa0a6e70673 Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Mon, 11 Mar 2024 09:44:05 -0700 Subject: [PATCH 27/37] Update the compatibility matrix with a new ResStock column. --- developer_resources/compatibility_matrix.md | 24 ++++++++++----------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/developer_resources/compatibility_matrix.md b/developer_resources/compatibility_matrix.md index c9440071..e24bf976 100644 --- a/developer_resources/compatibility_matrix.md +++ b/developer_resources/compatibility_matrix.md @@ -9,18 +9,18 @@ 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.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 Version|OpenStudio| OpenStudio-HPXML | ResStock | Ruby | Python | REopt API | Modelica Buildings Library | +|:--------------:|:--------:|:----------------:|:--------:|:----:|:------:|:---------:|:--------------------------:| +| 0.11.0 | 3.7.0 | 1.7.0 | 3.2.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 From a49cfbea23a8ff99eec26bbdfbaca9467b8eaccc Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Mon, 11 Mar 2024 14:38:28 -0700 Subject: [PATCH 28/37] Continue to improve the residential docs. --- workflows/residential_workflows/building_inputs.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/workflows/residential_workflows/building_inputs.md b/workflows/residential_workflows/building_inputs.md index 40258011..a4374782 100644 --- a/workflows/residential_workflows/building_inputs.md +++ b/workflows/residential_workflows/building_inputs.md @@ -12,7 +12,7 @@ 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://github.com/NREL/resstock) 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) @@ -88,12 +88,16 @@ Users should ensure that specific assumptions in their templates are accurate fo As of v1.0.0, optional boolean and path fields may be set in GeoJSON features to indicate assignment of argument values corresponding to ResStock dwelling unit samples. See a [GeoJSON Schema](building_types#geojson-schema) optional fields section for specific boolean and path field names. -The path field should be a relative file path that references a sampled ResStock "buildstock CSV file". +The path field should be a relative file path that references a sampled ResStock **buildstock CSV file**. 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 and [ResStockArguments](https://github.com/NREL/resstock/tree/develop/measures/ResStockArguments) OpenStudio measure. +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 representative building model created from mapped model input values. The general OpenStudio-HPXML/ResStock workflow is depicted in the flow chart below. @@ -107,6 +111,7 @@ For example, the "County" parameter maps various weather-related arguments, but 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. @@ -117,5 +122,5 @@ Building units have variation across schedules but not in terms of their: - 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. +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. From 008cd0a4472c8e4354a259dbb5964a5b0bec7890 Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Mon, 11 Mar 2024 14:51:42 -0700 Subject: [PATCH 29/37] Update the workflow graphic. --- doc_files/os-hpxml-resstock-workflow.png | Bin 62182 -> 61253 bytes .../residential_workflows/building_inputs.md | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_files/os-hpxml-resstock-workflow.png b/doc_files/os-hpxml-resstock-workflow.png index 7887c0c3c2b874b8f9b49f73ebc8999114204f8b..870ca4dc7f5e7ecbbb16b09640c11d322defe904 100644 GIT binary patch literal 61253 zcmZ^K3pCUJ|9^c{x>6~UAt{nux!+YnsOg5>32AO)?w46Ul5&?@GJFat_xoHoavKXF z_sg=2xs2IdHfGy@eZIfT|D6B%pEJjK@4UC2vprvr*W>nj_Yi1&>iEUu2M!!KWpeNC z;{ykHstz1D7<%*w_n9xOEr%mqOej4IH&gK2*{8&9bjZSN0x203svRbnUhAs*6I}Y!^ z-ZUy0=}_3IsHV@0JSd5KR;Awj_0_9apZ~f1b}LBn!D*S1nY~4Q5?e98JI{Zpt=M;H zc6(HxG?+K{V#pz!68K{92ffP=(EDGH{sX~IqW^sXuW1*3_TLwPVmV*l@&CC~=EQ7N z;Qzktum9i6Rzy7~%7fh=8Fc^eTdjyn6c5xJo;v@(FZvez8m=}WsQUDO-W6U~8|uHM zUnjGtExDg~gIt>Y|J;#&AU0t1%Yzya{>W6LbDP&Q6i}_qR@QT(Eb}}TD($FfeSP#g zD)X2!2~)Oy+$QN)ea z99Z*W`?~e^+;Qt_uWxd!pm%aMb@#55=oN&X_EUvb zT2h_Qj3W?MR|%hqe6_#!?lxq?OtR3EV@@o8l;%e0I-YG;eNRx%S^-;bBPp^pX{lXb z)B+KKOgF@jgHr-U)cTtfbCjm*G{^UrHg?tN5)}_n3L|e$iMR^X-7FZen10pzVBc=+ zq2K@f4l6RgPp!(HNyG~&W;Xeg`hR3AyV3}Kv~I>Rr7$u{Ddg9MWmSe`XakmaWRchb z!8`$D+>+_3wc=1SVC3&WP!MHxo(KanGGw z6o$Zpd&9D#P;jJ`PsEE4I{S;gwAqwnwDn?TLhbUV+xT~|TOTc>=EcA?de=sAwe%40 zsX%$c*mTNhgZ-i6bfBD}duGXTbBI&v4EpGTT4crl{e^Fzo;|MPzj$Am#%9twHWriu zCU1nY2M$7Pd$S1e@Vv}LgpP#t9OL!=c26;Zk&~Ax;1g;DY%VWWL2ep?!iHo=_K_1s zL>AbzlouNZADf3j2=KgpUq?;inXmb9+RJCs#!MSSs*TPsb%+P^UhO@`-AUn8|L{kI z*?IQ&qszPOETwPH{RpoOlO~%3s|(t~wpS)o5kJZ_BDI37`9 zgS>;x)-YM*i*$T}WM|%oQQfkC5swLT+B=o14WzS2Si;%V6%i%yByWuu&@jR<$iQOH z!gIomIATGYer*VuNtuGM{>g^e7kbWPzG4Yr*AAMh-_)wd@(;B?(@&FP=Neu)@tsj_ zwN&yL9(=#hb2Gu|`i^F&>jRx=ffv7h#StHW57ru7() z5^9AVF~8y}iM5KweIh*bSt8=(>nz^n_Ze6>_~aeCcihEg>6@osmOLJ9@f}-jASzp1 z-VL46XgnG}Uh3;$RcRxSktOwi_H(>PY>9STQ69oHhOcK0XW2=J!z13D^qhWtL=;+f za*}>4lukG9OTh!*FUXsxC090@BE4pAzo3g;ibuh(d1fhOP{zGel1U0#@q6Z39FV#Z zyI???#t~!QWwTO~iLuF%a>+0qbEJKfT1B*WRnr1rS(;FouT8y2#z_&i`_pwG$wU$L zOnuJoP))B`IC@Ziab1jGWn_K)xn(OUBUmN;y3Bv7*0_t&ld4Db!2yUqG)*AyJ%`al(5y(+<)FX zFD*8IRlf2hK#BrWu{25)Riq^C*)`KeWf0pTR)e0SW;V0*k19>1ddB#IApcez_*9bU zPA07eMUr&u3q3FVJ7b3=umM88et(FvFE|WH8vq#!uBSO|=ls4KsizYbh zSHP_2y$pX@){45VH)*h}4`Kwm{b2DWM2ObP}E&NQj46zua;gkHtAxTi-@=J^YT z?gb~lr(o%yT6Gpym+q;@u0D;vczwNHD^%HYTn>aqwvn4xD`@aC(Be1MNp)FILL1mKSFC599h|^7@-aNK>FLvF-^(HOB4FTW?IN?hN;x!zu&C%JWA z*EG_XV_XwHF+|AyhP|sgc}}P2gMwYup@EjyRvm=e2d_nE27YUw_$3xYu2W)Sos!;ryQscUwTKDnCh7RuMU7Wivl5 z5#(e$H*XDm2cLLC34IJip0&1_YJYwv#s(CLj!ad=nu)4jJ zg#R*8v$sYSGv5~(u|Jii1l_A^obQG>;jxGc z>?LfOjfA-ThwI+RB}Gzl$eqCp<0cittk&7>oe} zi$tP(ZPNZ-LiK+SUae@x9WM#IhvKj(7@+prl`Q+9?AcIK?nqmBaOiST79rJGEH%fc z*(6DG@xm@O8P@usnZrotyamgTyTYd!mDkux1!_KcxjAT+kDz8g(4@N=br}f#l_eH#$ARo+sZpV&aYvW&^N4NhZ!iaoSZt;7enVy{+XMY$Ve{yNt1~&mnQpGR5%ATpIGe-gBaddJ7$utpa+l!}uLd zD|KXf$V%_zvzPM;QM_Vb72*-+Iv*9`$d}y%{9TuF)GL$eF5&SM;qG^TseKDhH$?g@ zl4_~*FYmNt$EXL@JhpsKywOE6E}WbN<6rA-v)5we#nZ-jD$@R7WxDb+p5KT<#|Uc7 z7L+Nfxmq!p$}=MYankPV3l7S7LV3f(+*0Es9~KSoi^*m7ciS^DSItkRo8?8Qk9V6R zrL%NY?^T2>LYMdFHLR;4^>A2cXAPZ7>R(T-Jw8UL>R~oa=TG&NclE-9>VJGVuj%^a zOBZU+khR&Z<&|B00{j-Xx;LA?0QogTM`QK0xOUw(}VjlBezG!5QpPj*=EO!Nr|8^u_g9gp( zB2Ag>V~K8Ps|A-A*8p{#58_IbTKLCdu4t?brk zf>4B1q<)$1xZQsM@0gY(S97FcS?j^Jnt4oeZF1}8pf)w~hV%DB%aheE@8y%3P zPqF>t9ENcdK1sXKJYTQIYpO;=%tx_l;f+Yc?i_h87%NIi#w5IcztHOQ{(A9C{EMk7 zP-5BiR$^H~T^Rnjb=xr;K@jL1+qHQHhIB$dOkXIMP`_O| zfx*$=^pmn2uCju$+Ww`!5!xH$d@sq3xHxhWDkF+lRDnw=n^Q2*Wq#p|&p~m=@`sdoS&5#Wkx}p9c$C zy+pjSGsC|G#qwDdD5CZuQ_iuX1Qdsfa#^4#59vIahtlU(N~Z!2$($1HUK?0LV8!zF zXKnaa%-R6GQ<*~Uuxt9Ofld1*Ll%%9KVx0{X@@Ps;nO#scfDn3@|D}v$MquP;^Inl zlhX7*7%Uu(+#a)1db#1$wACTah4;3)R&P(c0%qN$3Ct}fp-nW1F1WvZ<8UFn9Q%<648vczj7Y04(eH4rzMekZTGO(>x+1>62 z(qcajejeNR-Mpv2*UI6^TH%q(X3MqC^W*fSz1oDPb))RD(qy@OeaCTQPe5a`>^S&+ ze>I+vX1kt_Y+19&eY4Emr&JOXMT1j;;T(q~?KOwp;+fbkJ~B#|_D%&F_&y;KFnLvW zqCePkypJ~KnK<6P@Xq`}(tq(HyW2%+$LxdW0;|*hE@tVd5#bOL|bI|_LT79^Be|&_R&-`f_ z{K-{uv}MfG=yHaK_lsH&*g5fNn&qQZ-tW8W^N(8O(I>p$@G9%D8F(rf7WzYCVaz}r zy7dU2iMo0_Orx!lHiv?7G|Kce;^_0?U^~(ibKUyuSG3n>wFYN8Wbyh{1?vdFm ziFz+(M=j;brt!bt@aykC9MtFRGca}-zoNfSJjSF+D0ps>K-X)?|GT;zQA3vu8)W* zv#wRs(oDtg&1o%b6GfJFA@8@4rHNbfq!fm!x8nBCV#aZDWpG9VlV!pVSTvyV2lK^? zPI6u<8v(<1WkZ8z|60~}t3LT*@4nQL{!%TymU&pr*B-@OHzC*A^$6HkL?w-12E17V=3s(bP+WW@(9cY$6L z(S@L5R?%<)FIrd8Q9j;kAW5`ud$=(U+u#4?$Jn!@oNl~##%ZuY;bh?5UyV}3mV~oLg(kaNeq^D67?=%3-<$U7ZQ-IBS_w%kmPfzxS*7L=KV8e{6Nlo8^Qm?v9mO zb(vr2(USL%r#66a0mJWImVZnsH8GWGgU+xNbr`a@pWiekB( zCucO<8NwgCtQ@QiVXZoWF@Rm%70t>Ajv!c%#faxbTcNtxQXv2riJHCbz}ohK3`t1$ zcaVb1*r&)S9Tl6%IqDP5X3`h$|6yV4*i_q0_cc2z}KjT&ck!$==+t#_oLh zm-bsnMIVg)W*9G6?f=(8y=G(X;RRphg}g#a?;bLOL-93K+tc2Az4>P5U9~uZA4cnw z_6u#SK?iX5hd2OE#nJZRuC&;`aX#|FVUpfR;Y{Sn*U`w4!p+;mq}wBn{)D=q8TH3K z9o}bRRAGz*%X@=RYIzqmI`6Wv0P0(exJc=Bu2y-G-X^hk!cR$@sycp(VX@X=9#e8; za6QcWe7B7NG2f(7>*6mimQWZMa=6S^1C3WNVnCeGDH2pQ(P!{96nneUFHEcI70Fcl z&0ZReM?_IXE(^5Lhf-D5th!&i=?idY{^s*?<~q_cYNb|{NtAmcnmC@O7Bh1Y#HD32 zN|!iTF|xE0s|;Kfw?(IxgVO~O0q^zm{MyLuUdvP))7l)Z{vz`>$t=B_Hy}>f3`~nB zuiB=_q!*uD1yZf0sn%{2hh{iGly=zu00rr23!_NKj&F)I@j<6ypXt$J>B~Y2hyQ6Cq#-UV7 zdP7wa9L1m%q2T!^3fen%Q^YtDLMNti#l8yL;_teD7grv@e56gt7;Atpt@L%W4VqUR`2=yG3lRQZ zPy9TTMkw>?y_d$vG#OP$#ZT|v07c2xzlhYfKz>lS z>=_c5bsS_peIb{388e|UP-v*5(SC;EeH6ZvzfX{+Ef?qaIKKjliR%25zf`th0cNg9 z+>%c1H_~HT^YwK{jZJQGWe#7k(+RE%2&|5h)NmgJ?E3z?7rOKGpt_vUFlY@`& zh&Wz!gtpP9K2?u4lWw|q1Lfy;o9lVPlgL3^!XxGGirKc-!V~Hs)??eU&Mz^lQ*dHD z@mrq(0bG!u!6z`El&_LtMfM6j9|R@*tgx4s6@m$97dGz2@hV)khe9{qQRxV}_OqV3 zzvOP{%GUE}-tXrpeNfs@ zleAXP>{8`9;7$oOkOL!-Og8q{!XMH)#F2WDsF3T$j^c>507NGs-G^tbr##UDNDOFEWCvQ-WD{G& zo1OZ-(Ok+#hP>GDjoHg$IElbO{6?OF(HSLPdcovQ7SX&Op@XO zudsb1VZ=54y`_S&mFarV{kkQ)5K0>z7wdD=d#1q~&l_Y7X^LTtSvh6^bG5py#Knor+=fK!9HGHbTkSy67aF6SI}g{1(yb`sTiU^{sL5X(hIeV7a|STGmi9o(k%D ztM5s?EL`jQ!fyO$CF;G*Fq@+06>f3F<)C0IzBf4;bt6|N6jJxl)~Y_(_Qj765{{9( zZU7CcW)28=&bM1^0EmjxgoZw;<9{anL*U1u5}rZfa!*^S(u(v7FPEq z7gm-(j(HMtjyd+ZBj#n=V70bA9Vb~ks%P`=={RAdUCG<(n8Lw1S5vyX>+_agVmwnk z-5lI#t*66z9!e?{r0sRU(uH7~+RLJv-&v7Oc+1e=retl-rhlkU7L*vLpD&4O-3i=n z2{-Deua|};0@V!p$o%V^dmr1>Oy>7I9+6w0%NHl-{u@?Z`P=ZY6oV_;+onIY?yZ#K zp}JvPU-@R-^I5LrQ<>+vI(eBZ(PSIHl6a zcNc59%VGN#Xch!(!hK6CxGlSR2>l~)c%UYr6VOy>D+!tg4PBe(Znq+UNrOUWmD=z; zdP7p&V`|!Prezop{sPl2Hdu72}n-5DOUKiHFVP(cl#wie7#9p?3@7+ zXLeK$&1O@mOk(*c4$&{<7*YL$YeH#7qNB!kaiXZnWZO>T#ETZ9>s*F6%;$yYpYAI> zzga|?9V*&=%LiEs55`omz$x~7j*8((Xe~gOaJ$KE*3%DudT0P3VSKXLimgI8xNMYl zzYu=9(hZXdSuIEOIA)%W=zEj@*)DL*g2pu{yMkM1gRxLZ_jxNcs5nmUa)djd1uER5;sKAZa@bDeG|oqy2Q&pZXZZGD5 zdx&CwU1!FexvbC;kQs2e!J5#{R)t(pT%EszWcvVH#rYrpjcV~2g*2^9)e;Jmm_}TR zI#Op#=xUg;YCaWuRQft~QDOtN62qpO`W^FGY^zMANKJt3t5xJn7Z#qI_B;V#I|6VCM;v&6%;5IfF)k~ zCD;2TAC*k*i018eY|e|I_4)1l4{Az_F*no?#R?9}FKQAF$6i=?8{Oz@DnW?d`(5&$ zD|3q{+toIZ3pev4E)OBc%|2phfgiCW5|OV2L?`izDD%OHB~8uMPb4DQ*fCCYvS*?` zQGAhW5}v>XcjDB`T91dD5YY3SapRheoT3pzghtg2l2?$=6TdpmRe9O`sB?~PiMf+# zP|@$!9zL&g$Y5^xqE8dZ*7LTpa}19)us^2hZE~^Aw`5jtM>Vt7RREF#zgt3LR=Z%vh~dMr@qX3h_N8^EZ9%viFjDRRTs$XXR@FuJoJW zY=6A$H(yu3dY-C;mi1;?V0`dMh&m_E z-ARJ$3yv2H@LkiRJ~?IwioxpyktZiV>CtEX@gZM_{+MP1ABcZA*YBe^GopEc-Y(6S zRX8TUCMn$zUDw=JyH8Ec4Uq=YzwfT|)BLxx;{X}X+%k8rBf&}7tr zMm43sJ9RyL(;yqgm`UJalDMP%gd0frM0G!jrHV{uBJ^cY`mDVWak#ZsrLP@*f72TB z^BoBzo&VtN;=YU@H1q@v`5NAk;)~f(FSX>lLMlNIM9yng<8f=Ms~fe7sTP<_OtJd> zbub0y8xd1)#4Bj^1V&xe@R8H0ZZvKDJANjCnvPRvuac;p|7_$;v%|$NMJMSP=^;1H zhLRSNMwX)VXn0;DG<}_O1!AWkmpcxN_$@hAzDk1JMuBMPucl3u=(zF#%7$k3bfkur z(SXDCc%-d>qX{sq2J){tCOf3Fd7qqqt1;t3n)gaZ@(!`k0WT5%0O=Gn% z>eIlt~VfJj?(4Qs+(90zd2-%hqc3 zG>_b1%Fv$-V&#V1{D#|M0MOw~aqY32;^E;bZGWBc^~8RP6}uSg2bNBcSN_QX`ly=Je6=C66DqvitJPeI0)e5jP? zs#RM_Pk6frmEg}by3HSmUnFJ-o1;J6bitM8`W{_y{r;{Cyu8uPO_m*OM3WR*cM#V+ zcm?xA)DGm~N;=L@$X2#01!XrFCbex%LzK{Gd&i=&Y2{%)$q$0xf=>M#7IZZyy;H zmfl1$)!2!09yPQXH`+pzkZC@aoVmT@e3a=Tz3q-lIPX|J=S*UldgbQ^XGNlBjE|6m zQ%>p-j)v0tVR2wpF~4bRTHn|Nrb}(D2-ns@Tga*R6qXHoy;xcs#8JUpk(aYnOLaO3$K0lI5#@r zh%94?Z#$C{1cm%v_qL{#{PzIaH(eTjycHA~yTgIr{$`9dG zyq5gPuWON8?^IGHZEx0I?sv)jVVfR$cCqSHXGuQ`xxd6M8Gti?o3x*?U=OPCc@^^z ze@G{%2N|rV6vygI4e@!(2De6ht9vP~nNMXp(UW2MVIz1ZT2*%_DJv-qtnG zG7{a1#{r}gwEVdQU=fCO;=C6XV=%?hY=q{WKqZ9%^xHvm5uakzn<-UVAVN z0BBbZXp6}`&=S1_Tb;TyzqbX-MnJ-zTIjSpLAQiYl?*Rshfa{2ONM?#{kDyi>u0ZF z+2zf-3n94cQafkX$P1%dRkwOOa3`65MS}4L_ ziH{M-t-M1o8kX_IOG~S98%TW7(LZ7wua)C9iVU@@eD%OgT;f08IMM|x=-%ICz29FL zmNO{kE~x7AvTmr2(%Xw@68?jXT|VUO2R4xl6m(fd30m$Xn5szZ)9| zCKpNn>UDueZRdR<$9pIQHg!BWFb>8$v(f;BkYf;BCX_$eV)1Wf=FIYs*u1RqWaI_y zYF_mgm3bJ>A{l)(bu-M*s#PfHmEEs3Z*I9PRVjEuoojhLA++aN1RAPtwv01&exq;d zHtwEJ9o4Rye#dpQoFUusl10OTYi>hmP|W6W<6wG$d6tVg%2dicTaXiRY8jF&+n&C-W(wAILq&g?c^G8E>TzuFGKYqmd1HdV)b_mO{)g?Ng#68K_wzS1?&s=V zy?9?4(aa~RQ&%!e!6d@~npIf2q|QD|J}>uH-kpEY@8*nwFHx{UXyKzAoGIMDsH#Nc*;f=w{)T=q7{^ zfx1$euzX!85G*$!uK&>HF0t+zXAr|14N9=>26IM?e;oG9h+pf@w5N;o85q7I)g-NHndqK2X?5M;BD?YO3?1dd-1~6V+k!^X zGL7pWS4%P8Q#CPOldoj6ZIJ`fJTtAVPpSBenqN{~rsN_SBT=b*iSS{TWG{E2Ea+U> z`$6^`=6+5w-jR@d4BW#bRa8(F>*jzocCwGHy3az7cf85H&G5Ro1QJ>2& zHra6D(S5fGJ>_^rY{jo@Ye6H6`P+Y?(HHxnmIJ*WT+ z=%c?apYnFAbO9!d{|e~0pCiir7Bd^8g@2l@}b3ifZx;(_Wc%Iq`S0K+C z4<-YqS{#I>Y8Mq!(gvGu2XRJ)#}J2lljL%(bsA+L59!*}zjix?)q4>9j&uI6;iEf= z8tZv5J>_u)n2zCKBMz9Y2W`Het8|rpx$U7p6b-@{W@8gy0IYR@$N9)rU*z$&f2UQn z)5aH4%ZJi5!6*U!{bRD`g%fu|9_D;Lzt~T49ZA<5Y2c7*3|dOCNZP`K;G}exWO2|Q zE@N!4v^?1R-xCde-(O@i#t!YmIJ=J3lC(u*T&0-XR|Fe?Y|7ru0g89fb$g`XPEfvUX z{sh2tohFTbNl09d(clKAATRDn+o>AOi?bSESIsqoPIs(|Z{#=u^dpnwY#~Q+;@nC) z6?uhQh>+~Uj;^#G!{aTT35R(FlcaJx!*!R)RR?^!-U^H^pI3 z1}Pga$X$68)reW@$m#5x?iKKmoo#OJi2QuqEpnnchn)WHNET4!+~}ZEC#K#5G%%XjpPyWea__we6$W3 zcl3{m`E*rTtG>OLQ)m1AMau1kwEM7;w0EteEQ_X%aWPs!_!|s;eTKFIhlTmpsf2pJ zm$McwH&iFVm^c1Y@af;*b;Jz8nq0`Qe`o$ewuSdDP$EWbwRW0~wYE`?TCGr29VNI@ zNBe8e{g2w#*B7~o?5qi-Te-N~oY!aGEg$`9mdg<#AK;q=Kgha(G`h)LRJL3Tud3>M zk^jB2Hpk=*Fx1MjJn=~U15d&$1HJ^zYq5~upBnEo#hz(ZH5y*vBZIhsnD^(yOQOB}8#^4ttgRD{C=-0WxgCuEjQ&$`ZMdd~J=H-O~ycH6~-vJhT zsmF8wbTEh_W7IOBbpH?HXeloClYg(dPTgx%B9z+(!{2zt`XpO*i2quLwu9ecK?Eu) z1&_Yr5Y;V@YW%BZwW6hGCa~=8$?#FdHSb6t64dj zC%_l7WfAPY*e@f^(yQ)ylwMmrD88bxe1srQ;+?x8p@wC9D<(;$0o=Dk+W`8^@0 z=-*@AO|69LT% zOyfbRyshvmmGyvog{&g$tTttNfSJ8!}^-Ws=4hdzYzHIRyIUhhiLjkb!Z(yX)#> z%q(lq$+t6S-B_~ejF z?W5@jrRLh`^V)pikwO!|B6mJ}wW>ysFSHvmlS4TY!l=5>9z)~5qaFq)!D{!^tI(bu zAKfg%5jWiW(-}L?8d(fcuZaqKA{fTBC11g*?@*9A*#dXCfLVA(<8|$ef%p7x__JEH zbY-ROnfD0o4ezkWW;FIhD*LB6ul!GGVWI-tzI%`c0f6j^MSc3p( ztcY;6N_3OAV_NMDQUReyPrCn6?Fl<mwm|`)_f_ld1Em#dnRYo z;$O=zbs$Ii4fThz?sMKld&B&&>rY--{GoeztTD^2m}Z@m=XoQ_oJmQyH|r9jow zhzv{Z#Kze4`VN0Kq+vNMte^Jp;OYa+(^!WnH?dX=#?A~lnJx}NON?2`dTIV?P0^CM zhc;-N`JC3ht1PsD6_|QUW;~4=1+45`ZpW!t?ggHE=Jh!N#wNj%@)eE;h;chGdCxVf z8n0fc><#ryZ*{dGaznFd6R${EK!w~k4lpK;gu`9y(o^DdtU#Dv_w?)OWEN&eNn*)i?a7Fz~(!*kt|1Johq(nwH-+cr5RDM7PC6 z7c&+ZW@b~bdFNvfYWIiT@(&&KwY{#+gy!~lx;Kt%-@O>Deea@fHF)ctZJeaET3lLa z`$*JC<60EWx6;!sQ7-Mf#RpJX=5{kod-r(~l?LloQe?^Bde5A3C} zCNp{nGv!wNc?8vn&%a=h*)Pm3&>TCVm*oF_c)(^W20llfWXN<5w2);7n%89?XaTN} z=r83Et&vf)w3SeZ&jcQa?aceNek+v5QcD%c359mLpHEGjUB9OJty6ELhD9OvyW3zS zc_^9gMu;p=2OYzU!CD#~BCQVYj+(WbH?%zH393kGQKHuMk65LR)+|< zRpL)r^n5|4`;{L<bp+1yrX4}LqwD(Y=67`0}ScP&bR+baq)0dJX#`OE~ znT)ntMnqUo6$2Rf(0*XFGa3_ovqQ<%w_6*}6O5wO#Y^HocTrbNHA0dJS#x z-Jkwc*`UEN!ePzL1tDTj@m_zUqI92MvAs+SyV_z*zN1xMqo6Ihlj1n^o+roQa`}3M zX+;koQC zM0vZmjma(ibHstWrCm49-Aw_EH%P=?U{4{+P`#i)=g~pMPq{Jq|eS5ALrd^XLxv}as4V)U0{|bHu9>-xOak}0Ldb26XVFbZgcX7 z!BtnuiZGu+JCj3Wh||Wqu7F7vF>YPj%#Gas0x$>So;t0=I9}#enobU`4~pye^nW|c z>8Y=|4#}kc#Tv+&Fr{~R7cRSmgx!Fz{O}C*UG-1vrKk2JQ-q4Tz1uY^q6xoxlinX2 z{tjN-BRoia zKHp+sZbR7DzvkUSMogr;x%P7gztJbj*#hI_$=&WqxpP8_^E7SM^eEX@{oOwE67j)9 zOYP6Ad7oLm!fvvMIIhSKw`|(Ow77Xq9I^e*+u)H6H5wzG?z%ML*w-HFh<<=~NbIC1 z?NCNIVIb9-f*;D2|A)Qz4u^B=;y@)5BoZWg7=py8gG3lTAw&tH_fGWQ%aDX2h!Q=~ zBGEfx^j=0tw5T)s7`^xIzT}+mJKwqGx%dD3?>y|i*4k^Ywts8Ay-h+I)7Qi+)ilqa zUo|xP0LE*1+XnU53FWsN+iGJTNg?8x1q#WxrdBvKi=T?poqlwIov8^deh$jm+>KDz zgWEE3+Svgy`GLYHlM~CPw`Q$2e)mdY-~3w-aUNevZv$ch%v&1t}w+&1d@(UAiDw3x^b=Ql><3X3|K6-!gsG>P{YL= z=q@C!p}oIP+oy^`)GJiGd#dRlJ4D?|sFkkQE>n&xYR`i?c}prl{z7_9viJQ+;B&1$ z*~t`4<-3xwu&=+x_@$LH;OW_K65>wp?#jx|A}XF3yUMhLf%a z)rxr{p%oH?P7_>W@wsOiH?aj@G+xbu(5ITIgUp9h2gK#r+f{q$ZL^MeHuPdS*WR z8DihDP?Fk}s#wqKB(Bq{p#qePz0VGB37l_ElwiDE(?bRK<0W+Tsj=h2^;bjlY8nLc zWp>;Nt9IItXZ`Pdn+3# z=7@d2bJ?TQp78$j`Gz>(h7p;glm2wcF@xvFe&6$Mi5>Mk!Zrn&j%Jx$w{Pe;ImzcP z>hAlaxugP=4%{B(1#CE6`s7Py3uDmQ6pJuw{~)D5cl^$l;X2w>eK6WH)#Gd4$@rw%R@k=ahM^YXWdi|C z1xd@>Ujx{doR-;;!mKWAPZEcQiVt}%%BO`M zTeBTnb`Lf7EEqIgtQkO)l{)ISn%bw@iG!uefeK6D{d%X^q~n8NCnw}2vZ&v3bd%e1 zd=pxQX_GVSh?&?LpCj+y@AYKA(oFyZlT1kV7>W`LMv*Juv00`#%j7P6oydJXwY*%e?qGQw!jX26_ zTSZqC-5jS7ri#$;-h><9bugSxU{n;AW&@g~9Gb3g`a&lzfQ&fX57!XQiPtwEv%aTC zKS;UiA(Ufi*81d1nc1KH!L~lXTAX$S_7}YIS2Dl8rO{FkGkE@ZCEI7RuRhZ++Uf@~J0$fPR49EJOkNYm8>!%RAioE8#=tR* z_>>jZ(;|h`NE;K?_9J-@>1UbxazijqgP$}^ChSrj9n|YTDm(8y^4<)vpifbvYztnx zjqk>^L}~UF-<`w5LG4QS{8W=a)}L7Py@9quFP_YlrJr=rP9-N50Gg>k-9tm^m_^1i zvnY+;2OTZ&j=TmrPB_N8HNLsxs9mcQckChz&4yCMm~~}+4?!n5N>XobB+>!HqLTVc zMDInY=NmAw^W_J(|1RGI@yq0gwF|ZSt4lgEEf=Dq-vV7Vg)>8jvq4molABT9yWLR)tu=dz%Jzj617aQ3O8#aj6haLa$AJ>mmv9r|KHO%^HZ@g&; zt~JiW+Jf>#g=F&3LR~-~dswRS7+ZhrszHnqlUS5kdF3lN(R>*nGxBiua-q;0T z5*8sQgc{~>)4yY$C2_Co3NjhuE{4(y^y3!Cs~5TNJ4jzY(B1<#jD{znf!Dv}>n|Q@ zM@*~FRQXTFD;CyjAFWpv?c`SLLF@ZNbly5USU6^o6Z?As9ULFd+tb7*SrC?|L*hM zsNUz1dF9U0>~+sm%-Yu0i}Cc~5p(SLrhVrJdvLoQCtgQ`$r??vY?auV|H z*QPkWhW_KOj7o|F{BA=ZP?=TQE4{ifrF-cugTo)3W2%(3L1}ETxt=nXmN@)E<}3HCc}NGzDLLoeJATeSl29jornX&)@!Xi_@{Z!u z!UlqR%3fbEBMq(zZS5tSHX3c@;B0LuZh2uIutdDHkW^q7X zNs_ERB6646T^yIw_xfI;d%O_cKYN6nnQWi2;z)V*VR&UK*Ctel5xh4P{*e?gQuol0 z`mwgD@eD05I+cEPM-*kQc|HFpya&5%rz>Z zOr0AQd3D)qG&i@?r)~Z! z0Px}%y|J1|B4$K6q1Wq=S4kU8efu?{%f%|lCkr$gP8socL)Z&r{0@Tr-v5T3AAdrd zpJT+%B=kM8u~7Z?DgfdrDZr@W)9TlJ<0mx8g@nHe82Dq>-@eH>9b#S!5-OLb6e#E; zx~0GT&5z$k>YzHC4Ejl$l#+x!`h_Yk3*<>O-vs_Vw9r`1(=quKg&Sj0wy0VsbXY04 z&zGcaBm^q|=4VO3KHN|@F%xlUQHuT1(_8Rx-hMW3j@K`u!j9KTBb*v$01!(C0^o8y?K`*y zN*AlP5+xLXv0Tj5k_x#)-9b;{4CsBLPIB6=_hT0+XKGr#>UQI5clzbFfVx)K1(b}v zsIrY(!R^G%?+Sq0g_HOa*I11@0Ufy-k5;QFO@F!qkCkUcBkNNK!OfNB9yF&b@tcFg z!0;L_|8u9W9|Y&G9-i#gm}>XL&o1+%c6PSO8P7ja)i1exx5*)=P2iRucU!jI;sO9b z01!-SGCuX>K+G&++z;#*nlym6tJkutKg6p#jH8(ikU|2FJcopb$Mh%k(Re`ZpQZk` zoAuPxQ->$hCk*+W<{x4lBfmEAnHOf*wLcjgdD|*#70Lu>M||?2enEQ3AV-jP@bg3> z5^@wDa@OMR=J>KzWhV90?E&)5se#v9Vf$@@^3WH%e=r3iI_h^?YhJF6P-OiV($U+`63X=OiWM zKU>!%G24Tr{T?RqInQ_Rcj^zItA^&>?yl(;0{1>>+!iEl$&%NdTT2bLALDyWLoxT^FE%!FjBN_%U$)mkxE>H?gvb!4ND6ptq%g^Wh1R;}7xW3K| zJ0gymOm)dTIcmh1%}X$5?M{)J2H}QBOPqTJ3J(-o&yo?xRZMt2u3rj4$BF^N20X?C zCuhFuLi=?oDMEpVvPT7a73JcNi0_xtn}Gkbo8i{GhH&D?4r=P%(GzuEUEd-^nZYRo z&lRAX9s<+pnAw8{Ixb3GhmSix^;tf9i{MhXUvc}#X0*c}5KwQO_o2b(@1ozM-+U{8 za)$)z1m^9T>b`&uej1^sBqLVHb@IaS9{BscrtMzBY4*@o>wWT2M{;y2f-{js_Lo;xv4ezB6ro{9zDr^$TskodBQjcIf>Ipd>?E3~BL?28NZ;iDCVk18!_e#7=l% zZhNMgD=q?{^P>GVaD~WOK5s*bypIk~VMmIey~g68`x{!v8R}A#*|N3ba|6?g7MdTD z!($Bg00a*AXg?IBF_!WH9phN@$WEtywX0IEGC@P{2~ZZXXf9|_)2_IJqB775gEwrx zVkQSCya>L8PO!3lV$XF^Abi_xzAXG$2a)ul#Zp4<*B)f@Vq9mE%eyBOw6bIBAA(qa zeSX63iyg07ucv8nng>w2F}|>4*$9n^D7m%ud%#a)H9|iUVMjmGkg06vHS4L^gJ`Z8 zyYbXezxkt1b}nQE6K2q}QiQsK72}3Ao`ldc&X!dnvM=VKTn<|UavlKy*ssGg(RQ>u zY|s_MsxsR`EEZG$aXSPZV&J!`w)nfKL3nF6)ag)Se0GrEyURea>Zx7rHpAlYiqzV} zcA8B!jj_NF=#P#%kL(oNSDQO394MKb!2jMS{n`Y;5r>+(dgs9=279_c88JC})J#}e zaKP#LUD0n*Y|7Sib(cTGeOoubh2WGw0X7N1Q{M?FV=3`Q3;}6tl`ST3G3zB5Gj&~N~}Wq6#0O=4e<$}A{~Hqq8y z0$S97nB9+9@^qu6FSRpY%Xwxv3yP+v2kY)Wv!r7BGy643I6FImT_sB)UWa~xOqZil z7p<}ozmU3+)xFn(yrBV869~TpWUv6A3ZPH?_VqhU{L=SQU2PqVrkn=x)BNg(tiPzL zSCiI=Y&bTnO{&@bO`Qrp1&1aTm#jqSmH0f-o2P?Ct#K5<=Gb&6>c2PFem6-dpD6mf zD7&&#cA+R5thhVb8b@&PSDF9#t4HPv@G-ZB^SEDXzRm078@&`+2M5q;wimH2R6t+t z#a$SyrTfo@uLRunPmbR9rms82`fuEf zzfRatxYVb>b3uH!_+&xPf5<1?xav_W!Nt2+ql>-2GfDmUwc4&l7S+YR=7ak@&3`8B z=3I}Bjol2Ll8CPFQX>*SFUZc$|Id24>;GMi;%6#-(uQ84)7_&I6=9zwhuE5>?f+75 zkWk%!-`y}YG=j9yDgLkXz3XGNBjp_|$dJ^ZS3)y%*47^s?RqM<`yRnxriz**^0`-qu%@~%E-z}ca8 z(OYG$(G6ym3MCBz7F#}T8+^ANaBA1Gl6RF}%~IaIt=dF(I34&zj#C3har6+98M72x z@EqT*=^cEt8LBFCX$s02U`#7~OKkiZZBn6&jm95u&Oa&Z!RFdqS!~&$zW0-Jm0{JLN|q&k#sbBaA{%){nU#7qol>_g zCki;>_bxZD${{nbxegi;aAupCga)u-od(UPDe%UEQr*U+^su?SBNipJBPFS@=?eVn zPKDcM7yn8Hp5ZEImfz(n*EP#f_9-b316mVgrjeCtH>-59Uz%E^GLDqa?Y zN6B$go%5?OXU1MeTrQ#OC#jt`EU|kT=eiyVTa$ z<|uX0`fm&Jcid&GI<*%X$jM{XLt5^IOM9l1Opqu1j%Of z3xBK*tM32egy=IK`GPLb8;hOutboi~{}yGg?EhjMM!42kt(?QFm<|Y#H#-Snoo@ly z+daecVsBJg#0}tQP0Tx?;zCunU!*zcZ1&r1<}{pvx2u8E)w4`-UlyTsspdN}kQ1$Z z7O>tag*w!Qq~EMWQw0 zAE1$D_Ftry0w|WE`WeEE-ZS3df715?ps(!TV%-I>2JWr;cSKI3&@;S8d{P|6cLHI8 zkbs?|eQ#;=u5{ec$(p5&NX>N;K9MB*fW_(=duV4`wQ_c9ee!3^vd5{jjaycaI@G0L zs-MCAPGvxU(1KsuDMMNhL-J}vvHvT-YYSZmG>aDO#TvMv%#s4mi&q1MwVgaRi}0 z0a2=cEhD6&MDw*UWZ-R`TK`Q#rDWnxQxTUGP2I-|*@Xmz0`p$e_P-Yp#+CX6*7N0= znCu8Z0ky;VLe6AX;vX|udK2z??${;eUjW>g?Gf<|uId<^wsT+Hu*|v~SqWOM81g*6VOCf0<9T7;wB4MMZ0?IN$Pff^hS&uv^af|sS^`6Mz_6lwE zX=$+MbY&UryH9$b8OCD-ukrs`O=+%%ig6sc_~_p*RiJNcW8N~O>M9N$j4UP?thjMC z#%%eSnX{p%Bqh>l|C#2<-8$~MtNih81&~x*{~fn9J%tNFc1M49yLsiP{Ol?VCA|LS zJLwLo#q=2!pm)i@V$`dHURkJy|q{nG#IV+^lTidUcPDIN;GU3x-bED8(Tk z(G~-ro%G8Hlh)1Hn(dnzo{XIPGPez?8zGBd-aY{HJP?eNA<8HERywK_RrerPqHnX@ z0CES^ZqnxX6{0@YQ(ESqyWPjQ))<#!JYradF7NucJ^l_G;1kA9I}9R;YJd z<6rhTaw!P9DEY;Ww~AX*5F|#~#1qJrS44;Pl8jT}=wEUe5-TIY)+^M>4ZoDs>(OQG6W@51Zj>zSHOi z2{qu<6QzX-&X0EHuLG*`xm_l#7tcax0exUBIeF*lartTV0ykSC=;5fGvH+PqgA~XW zdIJu(5l+{&Ntpd?4pX_*5biLyRVz)|?OGkmt#V6xQeDeeCGGG5p<-QAE3nFWJx9FG zo9}?t)7q4cKK-Q&^t^=g7l)eO+yx6$aO}xILUnXRY4M^~JMCfWz^y8iw_@-%O}(|- z@BkSF>`#wRfye?`gm|JR%Sl1)HC#4hHjHU}y|!~iHjAu*w=;hMC!qN66Yv81W)$_6 z1}cuWavzEokcQgMW>AJZ2(A`1yX=%Xe`xqP1o0^8cv)Tg;|M*uB#wGk9%`_HaU21s zEwO9v9XQa|Y7>_D)RD~1fLsxaUC#gw=^B*k1KS$(!>Alxd<>6;kL;pAcR*4+Vu^UU zKi*y+3O{J0Dkgf+XGF{X1|d>6NtcH(5=praLF4@8>@v!h8&bS7#x@;*dJHg{?bN3B zX9CY-$Rw66gN>cdY;Q$CSxZ21C|{p5k>9?swAkg1$*oa?!cKme{FY;*8olbU<9)z8 zq*K1T)k1!&j-XX^wxx}?mr!05if38cmdC1CBMsj%rgCHeDXyCz3cr4HFl5wjtTPO^ zq{;;8&zVs+-y+5uOu~JW)I0m6b|roq%B@7S?(wW{@QB)yI6ljv)r@&j^GuY3KA_%( zkuM2D((CrKb~6WKP4n7k94|lUFBiyGQ@@ykG&_kmkZEwAh(D(DR@OG~&Egf@{%oil zpO^3_NANlKk1*{{x~Wz3S{_IZ#ST#}JjiSG_`182t{{A6Y-4jD;p%V&dQtMxS^HI0 zF6ok|t;Xm%c-sStFS<{!#)QHVVL`%L;JckFgrR12n&pSaA47zx@V`u?{ygu80Xwra*;fx$;%Dk z$R=Z#p^-Q7hp?sMVvvWp6V!~rgvUY@8^rEg#z!|piDSLP95Oys&16mKLE=L-9r!mO zz<62H{&jcTk#rVrG3|Adqk)I11nLw>4FOGOIbgg9|17Q+!bfsY-RQ?~CZP!P0d$Iu z68ne<0C>x0^hU_tpy*^0qg5$a(;btNV*(QCJmnFVl~O7L2syxl<*MBOM3|i z08?DDa+Fyk)LKC}L$liJdy&v+5HwJUDGe3s>6p2;T_NIVe}9AYvAqw=1K{u(E)O4@ zZG(Ap5!l{5t&DL<)BV@VciCn^cLDEhJbO57v4!;4KB=%PbRs+AOi|GOsS~`|C=RcW zg&HJ61`?()Z}O62dH=(>ObJCN!v)WR#n?TZ?@mgrHmc}{ys-9_T#-X1ARLrRaTgtX z;@fFqkqT5OF4DYGFW1d_vLPZHSdGfJS0?Wwa0{J=8=tjQP~!tZafb2&GUGW{RGK(v zj0BJ>^nXzv$u5`6CaE~21Vs4}JhA>>gEV08A|pCR36qbuzhmoS7e>8>i_+|y4W^u2 z9MF@?19DG0M>zstHPT>%`|8T>T$3hWRyPI`pL?n|X>N}`q{u&KY@#5T!FXa<1qS=Y%8rJo5T?oGlQhSE5uf1$YB{B&79HUsY1L;F1%S>& zJgapx)Db0D18izYn#s{V9m8ig%^F0BD*NvX{W)Qq7d`OaYw84pSzwx>An@`#U`YM- z{f9aGjYf{u)Zgdv_J`dMNy94C_yCD2mGEX6+o|PLseJG()!lNbk}a??xlSmP{F(_}Eg zdwS2rb1x!%Y?AK}TOBwlNIhC}y=uFGXblJk%xdC8FBl38$w7&hWl(LKR?RLt#cGeX z--ISGBtl}gssN=uW{){Ng7yNvw{4x3>w}bjSC*d^FC=C(otA$D4B}#ARGz&(%^2~t zECEXpyP#&7zms0AJ@KXJe&j{64HUE0IuuYfsQsf2XWhZ ztdIRMbj`&P(KJuBbw^((p%6R`YO7FU>(GLsO; z$ZlrQJCv3L=xc{jHU?+UPSnW{;d}F6FBCS_IFD~n>z}l-(vF~fn6MVB@y~D0o!k&c?jK8) zwQPCIt(8v(zmpi`ntkt!T#XU068%*9kAn>X0=QRtDcUKQsxBu$WT5AF&uDB^R+pNU84bHEfY~jt`%B^CtZ1hw6BFpg-GvspH04%bV%Y^vvMZAJ zi@A8s@6zbM{AhEgnDacyVDe5}#N|zBen(~5cc7bng-XAl^Zh7=3%Bwcs2lwf@TAG| zd#yj~|pA~wg228f2bK~xBaAe$8eKLH}f>v~fCJllKIy#abO7l$(*qx^(ZHIzs3 zKemV^16OBhvXipYSB{6su%5|l?R&Fu*WtZwQx*jn+3>^is^#}UA};p;Ex-cb(SEmF z;$w!q;%T3^{FD1k)Q2CepfPTJ<#Gb#ub2-|)zM37dM;yM3F z!`$CaOS#|G5N2CPVt33R z(KPhYSkE@`iw_EKDQkaI_CfP1k8vs;lg(kdt3Ct5Uu5EQdJlW&b5NunA<7_arGgBD(`Oy@z-aBh*V?S`PXU5$ z^5!xV^3N^1v_S%6nI*0>J|C*$w;klMy$rZdKulXRB{+5x!umdU6X}dWAEkm!h}wDX zuFNBddd$YJFP0OaX&4D4XcG&WOCVJfoN=Km&`2x%IFP^tH`SAZ-%cMB%CZLnGg^XI zd0%CJd&E&DU1t0Of!F3ho23`I1kWra6^dPr6s#xW(ztX9!MO>Yh^O6BqI{nVdY-xr zmEk7vMk*8F0}>OCe;X4m5hW6k#6QGNi67}`3u5pky&0ACD4g<0j&q1LCMy;~zuJ9b z^_if2BxSGbyKaC?Kr~t7q(#Lm`d*W_$v)7thr4hTOJZ2yikUadqLm!a+z+Q8zp-rP zrD5dgmbY-Hzg-%IH*K%8MPWBlpEKJ$)NmeLDE}rUYgZc;S1`OR$kmO+v1Uj%=x?J> zpFg7hQs`!D0u&cD?MYBQf~cyvX{f%Qy%2J~bgh|(C(PD<_7|otOF<(#l46AKr-mD? zbUAJ!A;LM*1{A#jeGmi5`BsWCWXKo#8moUYcUQrYyVrH5c@#8adqZBiO zSO?lY;ZZ07jWk%X<`fkUHy)gVR+nQ+C1_iC5V6K^VQ30$xZo+Y|MZ@1drpSVo~!Eh zdm1dqoO{s7vi4uh-Tq#p7+UjrP>8d}Lg;KdJM5=Q&+nuNCHxw@UTY(v3KRM+rVgeY zo4Y6tl|=XuEy-zMFKzztbHo}zrOWi2a2A3B(x}#Ia5A#GGaT2Kuw;?;0opiW;Y23; zXL@)DQBya;tN2%0rh1#73mR|M5K@Qd0r~6jJ6|n zV*yWtD6Qi)nu#+fkNl^zLB!*R);zYV_Gi0{ZvbVG*2cUhO;!>CJBJhgnto+*+Ua@A znY~}fu>lgaT|)F*Trg6VIN&?v`EW2JA8l^VFU=PNa3j>SLC5m<1wwsB!rkd^Z=8Zn z+ME*yd|hKNJh@sjE@Os+Aw!IRTe|)T${wz%fqom+oD+FxsrpMa1CbETtvW>L(h(cF z&zXT&hFk@`O)--$O1hNy(!>@ndv8kol$cSFgO!*~2eiS-u=kxFSLhQrjKyz_9gZ8S zsNlnZ#(aW{E-8;_=_+O#&?kRf%s}6T>8j z=3cl^k!xF9!o$lmfx@LLSnvb#lgo8#1B9|egKl5a9oSUCfkq{TAPo-L-!rx1m!|V8U^?d|lA?}oC6oCCH*@b9 zShJHI$NYNygZVv?T&KTrUG&n^%{Zzr$Ib{$_e1+Lh}2}-)0IuQY1cfZ`V&wDMN!B* z@lh*;TLtoGupru0{WSNy0KbAmhtK54(QVo=EFdXT)U9J)c!mIx|*O}%=Ih$3D6_b#S z2SJ6V3zFsI=H!p^Uuhy7LR^i7dJhrEB&ombo#xHcLWssziP9dmcWkP0YM;g^)B@E+ zElzjB*t#cyK45Gg40!q&YI83xCGle8HR zCc-!}m*ci>-`lbkpShPoMcH~0a^-6g^gp}qrWABiIrSY(ig(>%Yo}RBsOV{siBdS6 zp(QdLBs-sKY9lip^F(}>*x^>&g6^)&UoJDy!7K|>K@{y{69dCDH0(cB+=tl;t?)nH zmrKV^;n|3lokjqaOrpEJZb7AswO4J62wr?bO+*sgs_r||@h^38a}rgL6m7RmCh->7 zey@9#A|hq8EE9)a<`bulT2_-^wLx#U4P;g10xKU0SAy?#i|E~7q`}D@kKy~^wF5UH`e*9>;l(g>e5jU2Y zOSvu5l2E$gfUi1MzQJXX=#vUoOrQR$IgdO*X+52I-vgAvlT2+~dBoi`372sE`*0-$ zx-LU*&9+y1_8{iN5tic*Ytab5pd_+!`w@dHM;!RtXkv*AV{uEC4Y#6JAE;Lj1rbyWj<$sH(d;CwRp^CwozyFgxZI{0pD#lni9#Iu+=sUb@*uCEY zgr8ilyOb+lV*N|S>4yo%B0D@^bXzM7_85ugRTAlCj^2G<%@}6ym@Kq)xwj^vjV8*+ z?=TzB7?wnY6?3UJ*cgvTp`I9wI^G9Brx3#L>7@SGzwj}?sgwcT5%+vA;jmQ|`5gJq z#YYG477eKJ9zoczd*GI6LAeeBCFZAk#i{)uvDwC$#J|E@3v4O0Ft~bTVKIJ;&abqm z7Ij>gf4cj1nQnwl1o1I0x~JN88B-tfEF6)344(OZo<^HY|J2Lwv8bq$D8BrgBZgBI z5pOm7$D%9OT>CdS`I}ulKM9uAgeQ|0I^}SAPERQs`fPS=Zi*(3=<6eY_F9xI0F! z?e9!JE6;H;)H6zxz;)Ss6*K@EU1R6}Qy9sM z?A#wRQl_MV&8#8%v7d%94Vzj5Q=rL0BwEqkm+wsI*G1HN%!-Igf&MFKg%-Oe|IG>V zim#L+XbjmL5K(H*>mmX7)yqFPSQhoeRe@8Zm4i%yxSU1=YT>E#n31! zSdwO>`T+=BUpbEmCuSg??J|+97p7>%moEB^(>iQK*7@BwNN_atHIU-dE{Y!$GF@SEo(?%COlcb%JE{Y<524hR1P1Dql+Z3PaA4&c2;*ta{aso2|F_&-2Lt zVI$KC#)-$;F0A!;;pZzbId0Fx1VoywmtC5%lMc;b816%KUR>7rm zM=xvkKbt?t=W~&JbCyXkIky1AvRpcTM{-$srE9{#pw#4;r~Rigr08ar{qXr}89NZh z+GK0K+tyy1M8H-5v*`$tji|HxpWtl{+PmEc8FVKWIY;4qI(yk8XkT<-m(kIi_Gk;! zLl~86Pw87T{!8avnDE{C(-7BVZqtjDktVXYWQFtULA%`K-M6QEL;g-Nm&K#nn`z?X zf-kp9`hs#hO(+*?7;_^eSXYc=n5kDPq+zHhtMFzHbsrOUG zinjNv6YcK^Y)OA|$8cW%(NjU#0Mh=pF&~tMP9|i%6h>p~@xiXhJ`TD{cpyXf&v6v{ zsQo^Eu>9@lB^dov!Tb|rmiVXvwki0(%a?6cRVxD}%y?nFLS=TerVh?g zq1ES&n_0g>H+ORDB+L7 zGyn$VvLL2w8F>+c0@dKQqz&;AnPQR(`iIjOB}`ePZ$pqY0rF4#vshf(sUQ^Po{@W7 zu{AwA@Ce3(yeT9)fK9WLnH5qX``=+&3oR659a}v#JTWxtqB2#CoWs zmskq_e@R-{oW}5^YQQN1eUQQ8qeVcOnzthycenZNbq|=_MX8wbV#%f(#gP}ZMJrjh z?lV(vw~gJ_0(h;1p4yDXUq3ar1RzyT%ecw!km{7=Erqarhle+cYH_IM#gCVx0nW+1 z*SgJZB*$o1yC$bv3e@ro-* z#H*Uk;36z{J-Kr}%idUW4^#;-7lY6#R6S!F?Bbk4<{FJl8=q(3>)M#SD|HOM?T!VD z@C5D6=lxB0<2B8NKXku#{Fro&!u~_zKm@fu5n-*9Dyt2do7T@7MgXqKQnY)IO1K`C zOXa4QTOux$k|v_G&9}6R((DTkB?FcD+=~jC=T2?Bin51TfYCl9;lW$4Y-7e-Q6^&y`Vka$qjODi2l0)5Z(6^L{zn zEdf&jG`dzfFQF&@zAN>`6}#lcHhv+3VGt>FBFjK4)N4((`T}nAd7+s1M>sCfSu)ya zp)1s3+&Eux(~G{(@i((uyDm88=)Qt)wzq{JOq~Z@OOkP6v4?+Tiw5t-^~`*Twie*n z=v2xm?o%E$yMXcun|&U0^Beag)wxvz8Psg5x;ns%H2V$==q)~8@vZUrhHKUEzCZl+ zf)&xSzv7u~gDG*a>$5SRa8`}M%rIvqgy1m$rM^(=e)dR85PmX0*-8Nv2A>cOsF&T| zY3n@;%ztp)T8S*_M$iEAjsoG|Txu+R99U1?+x+0`J}C%nYi!QZ+N#3l*vx@!%19uc z*vqU}klK}z@%OWB-Q-9W*8L%y7&cR3_t?BUJXJ76!+h#ALSDy!Qg|;i#ArC<9=jDr z_b-y~>xw+&t1HA^%Qb{H@FKq|BC|B z41CL|0oxW3Tq=%5|A>jE-b%GuNe*_BO%qPN z=u&Irnv>VhJFNw@=cuN}*ltt+)8};Gg%Sps;ceCPkG|2 zF%cmj&85A%i!n87eCYIFS85^{({{Y*0zh-hT$xSaeh0{~LNPf=uaJIABvV&4kuQ@w z;%*I>PBKH8WWQJTfC=r9BdWtSiJ<(2ty;FvO->Zvk+DSsx$PSmN$N^!G1><9yB&Y@ z=#!>V;x zkcZ!=M=~`d(oYyt$PFDYNt^_VXO8Bl*M3eT?~-8Ub33#6~3;|h;`O;bSF zR=lhnMqb9ycnFpmwTb4#UlAqP7VIPZ(d#=aDI|XsMQ#kUI8UmH9BR)<2z2%kMaJY= z{cev@FxfZDdpv}bRJ7beHT()0a`Bwf{uUL2cw0}7vTr-Pt#iaeI&%>}566vO=&|Ks~P^?KqD>6H}NSZmXog*lViZMdwjPU=aFyll@I9 zYn6BufQroR_iz+_z8c^peZ_J&qJn9Nhf zmr-#A-docA<7Qsz^zjwrJ@+dsHBeqWvl)&@rIjrMBQUKVn_G(;#Pvz-92v}K{a$#& z)54O@;8kmsEMXF|Cszi$3*tvp;cU`=5f0?>1GR6c3KrW0R72?=49GyKM+09fE4Nrn z^nrybOTJl|Jj=RXHAJ}irrUoe;M0KH%A0DAaaIY>C1{!plo`aI{_03~ZyTK+Ic+(Z z2`N|m46Z#Aq#gwKP4rf5RFE^1wF3@-_OXjtVQ4{hv+VbOhC|ubst*8~! zT{C?*AE5kpDT9SAYV}U894Fw#^X6J3DmpS$+QLA2URGJzXQ;<5P`5Qapw?Ei@DRTB z1#0v~g)xOZ>@K%FWHpK`D49N54`H8a&BkOYb_0~BR_K~j&@Vhac;P&5z#h>Y>HJRj zrM>rf$vCgDxZmcRYucsre#fUuBkl~gh0r|V%-tbZ#;Lj0_N{ob{kK~o#%f-($NuNH zOq0@Mt8cofO5mXeVUqUV&fhpUEu8$K$`giLPHroK*5@k`1Gky`R<94ab~6ipn4vO3 z;Ii-Hk)8^*%yBT0obvxLeo8Q4y8cR8j3|uSwM0!r(-P5F{p!+HKBKvMAVe0_`8rW% z4=!+Z+ehA0;->-E-ijJAXZ!G84?D-xo)-r+BYDwPbkXA)G=RHgO>SS4%YEEOXwDvG zEwZI10b>8#(*s6U6)>{L&dNS>S;u9F2AdIq#0757a4s*O#>!{(&;4YGEVCks(#}eM z2?nFO36M?cPagFdjke>kEYdpUGda}CnXSu|VxBh9YK}{n*F{N*A4dstH2jioZYOrN z;dFtBOv8J@5y|Ysq@Ou`mGL_>)7|%PCw{rWA>@1NgaH8pdd$MHFi)v1g&w0nzx5)mp_~xTnE)XAU@JYzgPJi#Ma9UmH^o9Xjx>cOfgD0|MZW{dJ830#! zO+Byj;rkQr!C!B|a1oK37>G?5&kuEQwwtd+`B z1zw;&iPf2Vw4B)ezCLB;uR$kQ`?-PGAABY?{jlRr zu|`c;UMkP!wf9fJjQw9T?S_!Y405XT%!WSDHHNDQvA^+7W8dg(pDeDkxjifH(>GkZ zXFTLTbM)IYGw9KtsG$ZycQ@_qRFvhZOvsIw$orS`>+&x?#S_$DmH0hL{P&oHKH?Qg z(8DMUwHErHMlrn22>ud=HOXcQa4@}l`_0|}H8tgPjV@tN8rqfh^C@qxbH!cpv|9iv zYsh1$zE8uEtDfA2o9G&$2RWB!l zuda`;6k5IqEkLv33>TjmE_TY6Qo9B6)f6yaH|j3N0(hgaD+2e0$}Gh2M`!gjBZ6u| zx2&@y=A5gy0rAzNzT@}!uw$(C|GE1YjZEm3Pw?op?j#cF^{H|-vb(+f?{I6tFXq3k z-x%{73aN7@Q8Q+{Ml&B2N$9oDt5S%N_mGnZZvG$BH>1)SIQpGz$?abbMu8x5;AMro zs5F@~VOLW@ccm8DtmLOL=yXKfdP?ZFsG9&%YIoXN{ti~LD zn(>h1&W*)=Y}C(pf%-GRrN(*U%j8T52D3uGN;LTWm`P&L9HmRe+IgzUMT?Tgq>qKp z1=Wh>3Qgj%O7$Qj`;Q$gRF1G?-7gN!QM-pH9Jruk7paCSi_JHjSpfELKP|-m&IX2N z!pAdBgRTjas#faPoRQ_bMp;xflT9H?R{1~f(uon9s;Ys?0EupmnIFY54^;5~ZTUd2 zX)kt9`0$nprB+YIZq`Uek6cPU>jq}~Uku+*Q6|t$G%n9(y6YKmZZZU)9yX~;H9M0SG)mW9O^`<$aXo=M4%CQdP&vi$v`EIIuEWBJ zkbp%P=anu4UFJl?+^n|8n8$gZcyDm0 zxlf)+oM3i?k7R=zq20C=_jyaVE_WIQ{e}OMQ?+@_;sEG4xrwUYcm5ytl6iGQ;xHgU zcU>Pmkd&-_Kq~Fs9jAQ#ekVSvb0;k{B|WSXmwp}_nDg3H)DoIJo>|ccF{`}EFliX{ zwi9b=by^)?{T!@`y@nTHCrMDz=CB$)xiuZq?U&}G0e!3(Mp3iDk46%8yqBCuH;w?D z{v5QpEGvK@AoZ&6Wuk6?*g2AbXNZ@o66r7CC57_S;!VbN(1Jcp z+C%tfa}L^WQqrV6{J9yjJf!=+B!zLKhM!?Ve@R zI6~5^?ZG;pD%^c?(^+s)zOL;HR@zI*@*lw4{}|-&RMkI1ndpv)FmIC`{W_);5E8p8 zD*J@#t3nx#+qt`Ywsf1bC2~8HXItv4UfB2N06h%4BlEal54}F&8#e2>@F(~5$9k;+Vh{ahTU@tPbzE1!@h@*O#(i9s+%>iVswOB8 zjvK}GJn);dzZE&01^UhWi7;}>xJLB%tH$AdW^V}yw9_DfWE=m68HGOY7 zKtcYaVtyyg{wU81G^M?9f2Zjx(cipj1w-le(%Q3m_t^N6n#b{>GOLiXU!>0CIC_@= z1;Fh6l5tti+xAKe-CR-b+HMdM^n66uD8v^ajKWFI#MvM*Vry&&U`DtN;Ajp~bCthsgEHcJ>|?M*fbR zYcDd;OlwvTMO50;5{$Mzi+FJ%{IfBoQgQUmH}?_0sh&o9!s1sKL0;X(BoTpiN*##P z{4<6_B+Bl0NfvTh<#J5fDen6(d0>UD<#c$#-d|M|>B8N5esOCMH~ITPj9#?nwFt9! zTp+%H{8M?vV&ZeC7x@Tr5i^*z4x0%R62K zi=31oUa?zGUZ1hL;F+q0X*wmx29iMQ&-yPQJVFTd@2(!emO=KTWy!}O*WR)q-ykrh z`=m%D6^wHX$@L(x__w4A_#E!5cflFV%2-hz@_7WXSS6@c!N>9bRPmRH&-R*{7)OwY zxeSsxe?Rf%on6+CV4k8Z$Y<-|dD$Y*4xUH)^E_!SOw7jhGVl)v(~nx>(|9nw*dE!_)3kJc!79*h&1Np&TDbqI<+Tw%QJ#afw=g>J$>rY!fJj(Y zbr&|lsqGiHi~<~kTlWIij*e`T?(OR=9VGo8hF}h}|1-vVUq^!r@4swhDDQYFq!;#r za8+B+Uo;n^*4Gq`h1dPQq7|am_U3udMrlzXR2$sbKiVThTJiTk@SGOw0tslS{q83t z7Iy3?rEfo76O!59y}NJ+@sM%vqGltvrmYBcI38WfGCI|Mw{1^HdB|DxyGErJhS7(! z^OO5hgk%~e!Tn+RgF=VKAHLJa|7G5(TwxsE->v6{oA0e2!+C$?HBwc`$Y?KKW`P0&Q!oe>$g@5?XL%avssXS2-$9 zJpC=fUDeI1OYiThmoJl4{hBT-tiAzB<|fl$0{28v44?#QiVcGuX=wX6!9yUaonx2y z(IQj1Omq^WUz%$5cawOK@!#ThkT@%wK;K4iIRh`}jz3yDS zc@wFg<|BGHZ%pjGXdKVq9e`cD)$Ir#x7>$R%+YmfGlicf2)*USd1Bj9MnN*Cb=8@!1rTk=P{R|}d~|Ih~cM_fG5FwblM)75Azhc$1Q z^w$#D@W6N3Ajv8oraPbOx6_vW*ub7JV8f6aa9&m-Q#`QHMy5Awx_3-ie*c_%_NZNZ zS>tKW_Jn$?+x4n{xd|@KpYP;20p%`UpRdUxKqvn613+2Q4@eMTn}E-};F5lgD|_Ly zC-rr~lchZBlC(Lp-{Aizv`(14LBXAFfjgFB&6a0-#|1WWITKyR}$i+B#{ed)cSi=vL@9)Jqup+*H zCMm-3Tlf9{_uw11Zd@)>t>RE(wfk+7-se1eEkVPxfHrHoa^L`b^1C}iisoSS#MZJ_ z6z8GLGO_4Atzdf2|K<1ICkpi<(K^TM_!@sx2yALWakKr;r;U_Z^%krfvj{OCG@%$6 zxK?v=0cSS81ae}281B~}SX6N5qtZb1-B+;*-G{sOw8%v8&AObs0W+V*;CcZIr~@*_ zt)c%KVfsOBEK@-4<5KCJV|HR7C+6B*l|XBbY;T5A)xt+J-E#Xk1kgH;&2Ly%#%}}e z2gHMeeRcin`!9jZ9iF?9oXp@G7Dnzcx%S|X-P9o}FoVn3V_N0%o9=P2Xz8jAzLl#< zf>j$AwdyQ$17PysOE5D}xJAE~&Ulkg6Ov2X}oT@EUN)5p#8ercJ zu&)VNa!Bpz39LcPpKV*XeHSF}jIfRP|2ubZPXA{OR}KUvR(kp$k^O)D8L<-Nf*(_z z3ZB@`OA=Oj{&z7Qe*&H95UOcrdEZ)T!S1qB)70V3UWdKw_0te;ULpfbd19&iV|YN< z!x_kQA9!2!)JhSk3ZGsp5{i2-AryLqb;r=+Z?+7S48@u)BawX9S)6$HN#aNA{35Vi zjsq#PY*l>q6DVI%|;dVsX2_a5Jz(alHhf%@C!z==Nf7xysHdpEtP|cBMlT z--A`3IU*|O@x|>Jri{;Io+f7Vmyeyv8X_mwOlhT*h3+7)XAl*Huj|$q%YVbkG~-j} zHniD49daa1q@{EqIud0Q-+%R%RVWWE(`74nyo3$C;9hwuIW1P+AI1ydlRN?UEeWV^6v;00_NVBVz zgtCS3`ioO@xFC8avlB{=sBmFJ~cIk`>tgP)Ho%YS$4b1ulPAClmV0Yq6=Z0e^8CsNICFha~`?>o8`@$BtPLe>M4rW$j2ze`R6!F7`_wu^)s%lF= zJ@{~qw`aZy?$AT+twwhNERP6Yd?>J1Vykgg<#BNcpd+1oCyq>aL|O-!0v#$B$Zf2f za~m6?9;?;WNdt}V>P{OwZ>Q)8;*SQZ0`g|J2X_ZM_6$H_Dj_6s*dNA)5Qf=|*(3Qx z!W@EF)z8uYgl5h@JhW{SRzShr`DEEkNWcJ65>XWVgGGofm}n=QtaX}AFpLNyE_Fvj zf^z=W2+%%JxWo_K#YrTo29+C#dBrV%dzf)UNnaw#%5u|0>W-;%!RI!7H2TiFivzi% zvETKp0nzSQ6>+)Cd1B)CD2}%0jwip;2t310?cMDX5nXW!YFGQj*)|2*5V@OZaq}Ma$!=KG8604bWsZuCMi+ zrhv@5pZH_AFk~PfgC3|ve6eUN``m=n9YNycqx*zNxQu=c zsX`3{DDw1a+lB_9p{`@kyR&prt_x*+)} z4W1RpQwwLn+L*D=bgIQ?E4EVbLW>ZIL)#v5DKS`Mxb{Fm;kqZerhU&M4{Lf!KxCHx z9?lck{?JJ(?#suus}V~4bOgz_QYtfJos(l+=eCYJ1b-qD0&7v1grHU0-4=V{^9D-O zar#h2LKSwllh85%BQLOyTQifJ-_@$uu*_#=$T4tNzIyfeacpwN6^Z8IL$>EcL``}u zGdWW(=3nLRApp!UTaquZCo<(q?wT=%jWyvJinD90b(&Z$gr7`7u8k8jo zYV)vMFg?M?7L;w_8CY%J)>}qoC2X8=p=ZZeL64)W7MHv_*2jij+q2mH%Otr-UGz$? zhW?zskrM+Oj%ktuEBB$qm2L2D(R6AYtxNmlb1L&fYAMSSpF^kb)9#Ei^zcl!qFy4P z_lA2>g@oeZE9vE$b|y=w^A4=>j*zk34gTV}JKqE2R+|)=A?w->&0?p<;|zCCjQZu{ z_ksMn070-c{WM)sl=kEZF5^|T2g2S^;{^~SB~IqZ*D(JJI7Hmr5;j~b6;{3>3Ff1l zWu4aDv?gQ`I~qKDGu8JIdmDALEhSqeEOcY!UIM@*nh5~I$3Nw1MbGQzTu3UDiN&E~_id@uBS ziMvF|oqviVZ)n*bsAk(x>I~?aerQOO{JS?*k!RT`+cR}BLrTxyY6s|V&_Nec8sLWhjL>}xE$OSX zX}1h#^N9gY6C-dq4@^%#r`Qj-f^JLef|O_LhCwE{hT%p?#<|dEF2NcVimDt0<NebXjiIea{1clrsN1g$xME%p&tHeXF z+|%->Zt$XHn(g7*pdR;^mPf;Bf#2b(;*-_lz#H-^)XS6@z;G!aq01*pmOinT7V-*y zvLX5CaYTWM+|easxb{2xH-rpzgV}@V-Zb@&r^or53V-lW+A=e{TL|*FVxdMg;L$rm zgvOEHNw8JB&R)+PSenydE(|eTtAjI4{>q720H{R@7Av#~wggT^L5iO1>UWufS%x3N0Sbt(6$vIt0Ik9#nPiT=B zV2Ulg1LY;3i~nH^?nn0FwR%^=`BX)S8B*q>8T(eNgtC(m6fAPFk6F2Y8X)c@D9Ney zk*iI}ngjDo2>@qDYIm$1ip9S}<4J`*V~?RWXODiPm(`RjdaQ$D7(}>Gw9aH7ilrZF zN;l{0M}>_o^S)QsQ16?SFjk-C?v6Qy;mV%cXFsE4?yGxR0oY?l?zs;f?{q-MoF+_DRY&C0wIe`J#U0;EdwLoFifZbKzCwDlCofdlSe;%YFT4+I}z zk@4C2xckGYSKmK|BiJ18nBd9=1Es?3t$vJ7FKj?125`6<8k{d!7sEZjW3)C(OM1)C zHm~-jKZuNF;i`q3y!^`Ltox;8brZ3`M%OlKmSiB8R#yxLVyZy77v(Q(T&k)D6>(rR z%&@5U8@$>}nE)MB=DMd`NCV+tU90RmKGZc6b)3bd>LCwY%QRW_gLpcAJGOh*XPbZ8 zP0-17HV{WVW!O#=)9ZR4%1JGuCQ?j#;+B9h{mg!i5nTHj38w04D!l{|?77&)pq|U? zxT1XWM>`?4xNiYW2V7h%e!?5`sn?{ys_M1g@eHM-O$)DIC&wT0Qr4OkI|fC({Paw{ zOllLT6`!U-%(gf*8yQe`sg!w`-WP$g6JxCg2XSmFoDIv|{vEpfA!#M1KY(_%w+qdj@geXC~DZE{dr5P=Hay` zbs(I8M+|)vDD;b>50b|)RHl-_zo+bSuIMShU`lMp&)f_qM7+Pv68KG(0}Gc%eH6DY z)lKOoUO&B>j=(v=HJ&Pe-9*-X8Z zLJG%#@qKatq3NUR<73bA0TFzW#R^<$_pLCtU6}(R$`t)Q%a3JkXsMc8I=^@?9+{M> z3^r-fn`4`9Z8a@p>a8ZyUi`w(CmmgJ8D+tj@-a1mA-?8eU&rA~)!kdM-`WKyg*m6& z3GY36;;w@rc$PIoQGQr$D>SEo)>y@dyOHS^vC%43rHARq#}tR&y6=0;RxPGRk58oN zuM6&{1O75Hb4!vFy6e^;XN!wi{KiU|)b(^FKr@Qne&dgH_+HxjQQ;W5?B9?b@4r|z&QdtJ9ScIl{u_b$*6PE;QqNV`L zYA7~NSNTYf>-Kl==lw@N-tv-1`<_JXK<*%uwB4XQokR_+eOBDXhEsj~4GH6{SS5zp zr<)+1L<+ypxJTF(n|ljExg;{pFR#L>kn$?sdms}|lrKB3UQ<+({L*%=kzvT$!M#n9 zvj#(ZHPD2CBX${vV?Gc9zOcohxTojTuw1zkhFTtopz*$DvuLLcW_eEkA)Hyw+7n+k z9IXE*J)D+zYSAGEBD8qUEbtoTm~-jSMHGOnp?!428QM8&otz}^Krr9Zm_#QX^UXL7 zH=S&Gd{_>egM+HJJ|%rPVlei2v3=D2z(EL}C+;H4kqDyVHd~+q#Topp}tRafhK29h8B| zjc~t+wm`G2IMbqD=J>dpz*gyTZ-(t+(|)KY!Y&@@3-Xxvwcu^(e?Bau)R2auaq@N3 z519acp*_vD+{eu3TfxJ29qJ$_V)R;9fFl6gFGEH0tg^c^(xMg9HcvRAIexvJ+k1D$ zUO8FuT)MGlC#8C5R}Im6totF>9yW1x;Q^GVp}xFD>gp)d+}qkU1+p9%Bd$WtOsB^v ztQx2Bp;9+myRlD`(ZCO5JLH#U@kKZlDT05z83($a%Z-=`!bC>Q23;)Gf;<+=1hY?R z`>Z;j74P-N;+QOXb854erjHPdgcf?OvDizJm6tsFOD{G^ztdPA0MH=_Nk`4C9H%xg zzhEyEjIuBr(iKBj3Q^B5!VlvO@

z)8NF!uFQqVB+=3;J{xVr0zcR`C=M-v8}4ID zNcU^~qIolBMBKNJ93~G!W5>+G&jbW;nyd8;L?=lheEq-5TaA{M@Ngi4B;2msi2wgK0^bq5z^lWQ$7 z7M@p2yGtX}g~9=GoY#srUk3l-ZGI|COwTa#5PVTPIYd}4b9oWY6#HEun#4=g;CO=b z4L^{!TX3z!MmFvqnml8)N-WqvS$NiP$kmCARpF=??;R+R_>=}5OO@cwLT3P4*{snE zU1##zEX0jwQ8lzioxxdkMEMx|nkY;L{S4z_6gYn-iMYl217lP`M(b%!&R8(1^rE?-4-(-|4&ymM0E*VzqY_n)`0$U_^ET&I1 zHzJoCkC$c~@*E5B$%(z{-oX*W=-CS*kKfDDWs>M|XGoPLCvCZsk2NJ-Gl8!*UK@SO zF-+YkTpBt2DC&$(XiT@NmJ&&YPwFb}-9)*J%Sv7JLM)=tk1a)#E)j=h%YhYwW~gnV)e{bHMq#z^Y;SgbcA7X9O=#&790SJV7MvAgiA z%{*5-{XX~=Q3YN%oVZ~Oqt+-E(k}>aXR>bUpY9|KORzZ#Q!u)>`>=T8->^#>8d^`i zEJWG9xeU+2Q~l+P?DFig1@jlf3kA4g#%>bL6jI*{Hr4R9TK`KKz0y4|CG~Jl2gx!5?ECbhSt}|5iP(r#T%&$v`uQ_XCngVbX_>= zk1mw=VxxzoK4IAgX>L>xG}D-e>w&5GP{!vS8$E(nb~VK8c6GqZ2yrLLqasNjdO_umS;q!!^$XD^_kZRDoJoCH5M7a6~M&|>f&Dy z=CacI4*VTgYisj(T1hV+cW8`m`1Ff0OmtzzWHr=QX*jMA(7a1dshJ(@2JcrG3ow9S z)ggLU(SH4E(E#u+5Rbet%QW9i3Oa6ncp>gXCj7DT@?UE=b4!(!@sgmE(BV8he+^Zc zuf(>E;pP|3hpVyI1{{TY5w2yr4f=P7Vk>lS<+=3`*qoYM)C#fAp(0Zr)KV(zd;sIt z+ez;a*xavG)j%g@W|M2=aX}>%7^?PG_9@pkcIO>G2`iOF+>Tr|nT^Gm!nUbE_?a1W zP2KL?Dt6Z&8jei)VMWBw9-3cVS_lag`xH0501?cN#r64uhwfZQQ$M{n1$nR-g5=xu z5XfL)#TJ5Vu7JP}Ge(HXi8lgqLW&Hu>l1=7Fp@E2Ex%b`TPj}gOiU7L&bM;u87HE3 zLv#owIy47_V^U;Z_c9S8rgN@JJA~ZFp`B9liY!ic0wUqQO}w~vjSsOPX**Gy@8W9c zct8N~t_G1S+zt8U5T)%Oh|CYM{`G3^GqsP9 z2I5aL*(={C@&muIOHPN@&rgd+S{c0>QxLN|K8lgbXcPHQAnf5F6dYm^doH;vPqBmj z1Rzi!!nc7#6J}py>0@q*s@7g$G&#lXtw8Xd^|$>OF!8W`aBw4FMDivP03%DeQ~%%? z{y;V&{sF1{#)#Pb6Q3S@Kv@d@106Z|KuKpg_?hLIjkC*lTZ33OS6)o-ZHeL(P7_Kt z&VRZ~LNpcP3iz~Wb!lz2gJ6+2J{=!1ecn1>FgxUDAqBEo+ahkA;gH{*C2L`xq=&N1 zmoH|z5{!@Zv%0kSCh>~XwtVSHHUdC~UydW&bruVT7G^6y=S_IUkdy%;B7 z!l-Fx6vyPLB4;{<_GOSuR^uXNHG<;Ao+Fe%yhq=c7=ff_Tzv8S6HYcUtbx8+P%V!6ZQoJzzbiJX?Yj5_|Oc&tjEs6d)$Iwsco_6pjJ<`RUZ1 zW4M_Y??St!3zvt@l4Z2CB7v!93ri+yjeKHqk@)o)^XgU&u}MSzc_8lj_pwIiO~b|Z zLI`S@4}{UlsA3?= zL@)ZPeTO~FlP@1v()%L5QWQ;w-|wIYjz6dwvo_UW8E7-|P$b4dL^3K?h64^&!%}ZZ zbkvV~AVenZt_S@-HnE=>=npeKJuR2Cb z!9fcP&%rx$;rJwEC_Y+hx_8A24W}2h5hROEkJ9ctfLuff)E3K1kc+YItj%RC@RJss zudkMUKa$4Rjy1#a#H=!JuT6CY&G*Fs*$tH9W1h8NN_J((q&ilG3uuSoPxBmY$r*iV zu4nWJ5%W*;v2ZgU=791BT4-W2FW@i>%~#A&Yak#N2-khN{W#e+ z&9tz8p%taugB0v?ZDJ;0GAgGLw_Hx4=@k^uMu$$yFcued)}gza-m@Dd*^#!Gx;cl% zPeaY5F}pU-G>+X2Odng0mmyrAq?!b8YR6KY>0$; zzDg<+Lga&lAA7d)_a%OEAG1@l#D~QBUmoNqxE_rfDIJ$}xhMJeuz)y|$l+weF`jFp zHR@-~;%Nm8OM#L6Y`F?nd{z&5K##Fvh3kFw8qbLOt34E0CP3yz{Vk`sXsq4NA>dS} z@}_-wJHGx}*DSA=AyICM@@&=%pH!Vt02lLOu`hn|Z7 z>~Fkzn*RR9+lm=ReBCwiKh~SlOIJn%V-_b+a^N^W!JHYE&wo{~uLZPl3Tky$o>pBy zN=@~dckR7ZQ9l}pgq5Q!1ubK0r$#+0-93< z1w>;jS2$xBqYVmGE=ryP(;3d$$Mp#LvQM7e!%B=X&6x>96Y8aHnJDLDp_*p0y(3|9 z-#A8w0%Ji3K` znX4rbFcsSvl)0hP;(p3!RfX1iooEB8`G?oe<(kbVo5O4ottL_q#iob9TbEE{>ZISy zHoBw5=b+yoB7%@Siz+ca=33;u!Q-hF5%BA*CI{MLoO* z`|$kY!y`SJQWDfzh`Q5uMl3R6SJF|-D*Jd{(SUA84S4xzrOwcGIRvA9WzO2)p4dv)CN*+{RrsoS7f(mzkXn3| zmb6y(3B1ADN7ew*IUX*HyyVWHVMjw(*D{a*|2Re5$6_RnbMeskjbd6{2Ltx8x5jE# z`^WG=Yg<>O8WsgbDox$pCwilqoS@>9)asMzRV@C~)mmnUu~i;m-@cL`R_bHv@9ECm z9glAn0Wq#4CFX9Yc%}5fDYez#e7<7($jI7_pl6Fzi_cVaz`f!e+mfPX(#2{x3bysO zA7~iDYetxeaD{YZ_mH9a)NUC(cw2j*j9umx-)iG*WrN%41~4tTLNv=#t@tU&O?o3O z@KgPcS~Z}obbL%CYa8L#Z8DsD>ImERLBwWw8|LY3Sc=JgAK*Asl-wEMxKp7ejPdu+ zsq17+r(fN!qcdekwn*g+#3F<-frpAm1Cn;dm@H7JeyA+>a=23x)0_9$jC$|n3K<+1 zuwPis>I8M@8pXx5frXI}4zy`QG9{XQjDI^dx6D1RiF9OW*}L2IHYZ@zxs%1ZRt>k1 z%gDbWu}>hr1?$qoHe}8h!?+jJ!u9V0~~@;ct)_24qj4co#`)yX+$QsD6l6 zm`yp7A$oq#t9n;2osCYe@rM#dNZA#&ePq%(jwh}r_Y=X0M2&|Jt3x@%tD`&b%#!3x z?Rk4iX}UBS=y&IL!qwiDqi_@$vU*V5o!@cXgJ?y3ts1V8aconJ6YuUmK_rNCNu9po zfHP4g-5S{UpakicjC*7|Wz{RTM?9^8^L49qn%(=9IZZZ@IPeKrt${=BO`c4XZW%j*fzwFV&)EP#1R zr6+cIQN>U&y%TAIW3VZw&HGkYP(N(N4NMPLikGHf^gOcn}Vxr_G4vM`L@OF@B|AOOmCP-eD{A$NRT1V1%1tW^8TVv1AB_m+4k> z)~i?vkc@5uf&hSMW4i;uCIcH%E5Ydyhw1I#PL|}@g9+rcvEJ6T`pzhzH`}|_hBhaq zM6vxQHNP96dtP{XNXl!QPNTG`lrF3e7)v6L{FJ%Wze{@j!l-A*0voWvux|A7)TEu? zXZ4%GX;j>Dflckbn>3RW3!ZZSPaNXcN@{sdw`(jER`ZkxAnN&)D-PT`v#6Lfl*E(~ z==|bS@3g$$ix-C8n0o5=TH|<#t;_t-Yi`^}rg8MI2i)Yu60_u7h}Ycu06=qK2biyvfay_Cm1m5&WpIrJ@w ze$mj){jZY7U%Z0RB%2jlMT5AUgYLdICA!f2du5ymb|P?2`q+y1eum!;YXdEv`(Mnh zSb6OX`DPfzEFxT>Bv*N&&zt;za>LvIUOUMNGM_`HnC-@z2R8g{Lx|x%#?fZlNu#$m z7-k{UoPtj<-__beyC-<5>6|9Y^~zIXo(_63LTf_VcH-8g*T~H_%b)|Nx>Pv*OT@I} zJvptbkZHBCjdSl%X%UI8M5EiVNJ@Ha;@uFa8S*6FO2utV*WSuq5*qetf@Jb8wCj{? zQ{S7U(Uip}vu|59AN}^Ixh^lX`xe?h^1h##49Yf*k=K}Wn4dt@jt;f`!gzpeGjVjw+H>2eg1 zE!1J1aR;NK)8OA4@W~+PbR;lVckNEoprKtxRGYen(hB3)!plL5^~+uMh1e~lByTh? z(RpB6I;{9Rky&#-a@TDACf#7X4IvrsZhL-Rl?FNch3@RQ61{32)wZTSqcPvrn-ceMd+>1a;^*lYtJg&>Lqxoe!|i)1{h-r~6M`FkHJRQqVgB z2pQr=0>kZaXOWA14S+Uym_lB{r|+`e)F~JdoH{DfXyhYxLQKtnlStTv7fcmbu-)d# z3o4My5?*bW5b>!_hVoB2%Q2NuqA$R16Rs#LiIpA!Wx%+77GT-5ebbJ`TDCZhG6v2) zEZmY#!WIkpMdL~VJ~Gq+r3mF2ng>WV-6X|^dO+11Yy1-RGEu1)bpo{8=zeV4*NbAg zZ0H#ONvwEj&T4yT>8$W-f`z188v_wbf3eNYOkDR5;iRkRR{J~Zf}n%2YV>w}1(?7_ zOYzX8@jMLvm^J5Mz8Uky(DpNg2oJ<=HTM{FzJ{hk4r!_&_mx!7a=K{63F7V1GFYBZ zoX6vm@_!>83eu* zpz-4vEMohtN*Ncko3%^7SFgE?wFi7nVVwF4>fs(_r zxyW8L=qjVboj?Sk0nz?7tX>q-Td~p`1(MIv*Efl(7^J2P6VaQ-5xrWBnMdYiMKGn&p;r;3z7h=i|{ZYu-H(O|B3 z&d+zhtyQ78emlkf(Syfw&QsoSWUn94vAIvnZ9%!3RL6*4 zO$vmpYE+u4=x%WcG) z)^%^r=DfD7*H!QjxOeg5`MvW~Un?Ry*w#+eZJuDQGg&{ZhLj*yr4P*IZy zPuG53Y@X;z$&r&fuPuFBKe`M9AAY`aA1`Tol6fIdh1RrC;P?2wbCesY{Goo|&=UWC)xNFmJJrg8w=7S7^vlx7`6x%)5epJyUv1*L>QTXVI5GO_)rfXs-phF$c*T?3$G)Hr+3TwF^;Q&FKkGR%+x6)+T4QVH zY*8Nkk|>(Y~AXiS60Z4>{a$@up7ozjq&bVJco^4dH~g2 zl|Iyj%_{Y+ccEXKTw7_F{|__GwnvJg>fMEC`m09euD0d)6hOH$Y}ph@&Gt>4Wr|3e zeCXZh(}k^aHWWpItt{M4W4hyF^C=0Gd;w6EF9X&?gjHIN7S6|Ja;E32JfYE0$-!PF)Z_NZSW zz_(JO=n!&j<|;hRa{*k|<|e&hzgQXU3!I;6O?_O`$=l|e>htCka=Y_xntJ6;`QFwv zxot*UH-mys*AhSWx##2kds6~Hr7|+w!%jiKDlG9k#&=+4z}Ip2*Ok6BiL-y{7EJI4 zoxIFao_gx4i8VHQbpzt^#Vv2#!J6gV2c`FG>Aq#KT-P;zHwih3BJJRvdpzHcuR!~~ z{2om!uv#^p05;!4=VzX3OtXw2xr=SD2H{WYq`lob98x?nn%umdLS@BIcizhTTRCb( zbGf$2@7viNncNdoDf~Io$>VKaN0+qedP$XBFhKZa(i>yj+d9UY-`9vu(H`wZnH-zsF33V-5!yo4WD z{wegyV3(M+oIrXDNkiXHlNh=A%QNQAUm@cqU#40uzs$C1-}K7Yb~c>7=mMLuIj)4C zRn7zPg|?OCpFgy-hXWtHk;vYd4Rz0(D;VDv%Va{#Y)2y?`0>{Mgn;>*A*UK3^Quy5 zp2ttL@#OYYH#4CGNzxZ7q~-lh{IcsSXpnd+Tj&RZo_+pZr^OH^Fx+Dj_>cRRq4&`SLy9<{%8x^TiGTB_qqSn$}`%fk+&}^y!gVi8{Tqw zQ`zc8dTF5~X8J-W+sE1bunoxf^@$B{W)i>*swflS96F>L% z((-dm_iHQKf**wWTvnJ4m=n6G@FIOV^_vWR*O(ZlYj)ckS$5~L!nuojj#t3{xqk3A z=G}0`KYva46#xhR`(M+q_m~dw5)Zy`@EPoZ{U1N5`oW~JpW>@9J^kzU-lwF!cI_~S z=JaKi-C=+5ZN5$S17=+lIZyPe>&b)XvS(AeBz_tkEqYyXq6n>c*-(3C!sUhO@{#UD zlRNTlmvq-G-2GNlv)|7aHoe*~F6uVdWYHV{no;r5O1Y`>L+?rChbi1*y0_$UN^yQu zo>bV4to3Mu%~{;9lK3Opbn7_HE|PRW-W%*Q?r_W#&pa4yC29%ULB#6 zsqo#WQI{25(Y7B&t#-q29{+l|BQw_Y=^c$L3cN57i+HPDoHY?ED zwo)#fqqnXahc@%tZiO#>HUHt8yPTOCm<(S{)Uh?B)~`vMwB5NO7g%q?sul)6-~F-a zRQ~qE`E=!>%rZ^-w4s$T4ywheWEzAn~mSv5e~3hWar z*hooQXf-CClYWYymS3lhDZ8RA`_3($&ldVws++6lJ-S&k_w|xX_GGp1$CczeV>fIz zA8?1{$_JL_2{>3)?4F?Mq;Hx|8_vbxc)!&hD`8%^-^x0!*OF9(Nq@;}w_McKsVG%Pd=FSX@l zR=l}|9KEwHv;BGO10+a32UyI_e)82L)Kc4}QXg#Q#@1g4d}b3*CD%Ii2%`}c2OrN)OXCO}HPTPuy1>6X>mZii8^zn*Nf|0j-AyViwu?+!ubQ#xxe_TneBoVF|M}9!Yj(lq zV9a}Y(e)ElK{?$PBR!!0z6R|uFR=Q8$C%9u^d$&L1*V?mo$>5}uAoHmjqXF1JjIyj7&oXMdW z!?dxn*=BrK-_PfFyM6!p?ceu%@7wM9dOe@d_v3MY?lnLED+>n}`==4%n8WTD@M&ly z$gHmxf13SR=gatP=B(f{CUqzQWD0zg8Y?@Y)RL#==5A0jm>JNt`KGbWmpA93qCS%| zr2dALLp!t-NfqM-xMIqS0q5o7$6z0B1!?^YA1yRcoV&%op@f>ovwGIVHgbSIE4#g{ zT|~%v!S-KI{y>Fy>tmKcZ1nr|R$SLx@KT}?mi6F3+z&^-XbR>MjLtpMU(b9BMmOj> zgQHwVJ1c9;$x&0e-@jL#Q%i6i7h!@i{H6M8DZLoDe#ReznU+A#sd{4%X@1?k2 zjSM-Sni#@fxZQ1OyjHY%S_!0SEGe!nTj0-yc8tCLyvI21dkxPkvvmQk-l6ypowfmequ=N3|2}s;R9o5q&xx(G6UTh=fLH3~|6SZQ z|GsN2cB9t>EMBtZ61Q9SZ!QjN!V|8f3CYIOrR|t{v?x~RpWRZ&6G}9YD;G1HROpg< zzL3XtQFH>#s-J%prC_qwkPQqO-IE(K3lF67}4=h ztd~Y0{X5wE=Xo$Ef~vuHri=|8W}4<1ZWLL~^3RPw98k`S3*Hw8m0GvFYC9@5%~~6A z*L1s;5&23d%L-wXTTvX>i0)|#L9IAb9T7I4OfcNTq1` zxLk^k@`1Y}bLsw4ohY_!Z?DgMSOv?{Ri-wLHh&HbtW1U6rM?9^dl{WKoB!~o=sub2 z1==>OL1vERKS&WK<+eBABHTcJ#h)G%&6duzpS7fZ1lRPjQpDCgn#RrzwW>K->_n}@r8+q0! zBkqBLjP_BBRw}Z|Gype&k4&V3dq%heW0T@P2Wv*;pvYE`O;O9V!OZ$n&VddpG9Wu8 z?sKqLsl06RhlH9a^6ePXLbrHFzm2}O9wiXt^{x6ap}ZWGrPDBtSgVqhd}f+;!t#O7 zYroi@)!0Lu`M0V!>n-`_$vRWIp&H=(nX$XL>5anu_1Mt z9XKss1q@iJIkD7JLyr$?_)^muq3Jm_vwqNJh9Yk@r*wY%?N*>EKOi2t$qlHvSq?)j zn8H8ZAu48X7aHMeiP)QOek~DFH{tWvc{61`w-DD=M=7elP+ zcOX;W{fSm`l2}51PKoDBQKHy}{m&Q~bwjMpfF!z05TL-=1S_cG!MlBK<4I;0?@d?E z49SD&>kphB2UT3IQ^u#5U-dzo(*bLcm3145< z;qmk`ajbg2bR?#(InOPakIkcco$D55cAa7YFA-zUikQ}~*%5H?#GAOrtJIThpS1qglpq_tl@^Pc!hO?_H{DhoQz$gh?*ju6cpt5a!&S9Ad96hYH02~{D8Bs zWpPspo>`;ajv|obX6HzQc-q{Y(zis~a-$>FqdM3d%$|MXRaL!coKu|?o1eRV<P`!e{H<(M3AePO71l)!^K1~@zoeA!={SCLlly{AGj~MF3}$BE zO%Gv5y+2Es)U(A$f7-s+{B>b13593ofdN!%YRJ48q@-NBCHaW@&iQ|nt1jkWuwH#0 z0@FjccRZsgXV)Nd7U+RDoay%_;H|$JpiDsNR-kkW@HRYc2oFze?4ighOh;;rI3RSn zDwGln`rb!F8DJ>0;(1`M-^-w4Yq(eP*J&^Ooe7!-f5n@99qO!Zh*UZs5-lqNYrLbMhoL7?*VEW&)rY!NugJuT>%)8^k&e3oTVcC_9^Jr3LN4*ZJA6?P&3}Cz;2WEpgm1pBXWEFIv7$LIyiypRsP=f zf*JGhF+5^Wd~C0kw3`L;wwtBP@)K4}Q>r2?9J8~E^CPx2p;!y8Oq{9EcGUyiY{j~F zB1dh*iMoZ&e_muff$ykz3krC|9d>;a8O&dSYy{GXT!Z;1LYKGew`B^DSpBfUr2^dK zHU-R{DP9v4OyJK54PE6{$vdG3BUTnRKNSAgr8qVB{Z6}ND1+E{d*ji#9?!Ds?D z=-1bh}fTC)l?1|M)k;!T;VabcITbA}hN$ zvn{qGqkefn=EL|cS!xk)FV}e$904UC*}lCe{6c=JotuGU@5jcxT(0!WdUcD>3w`$W_MI+* zE$D&p43f2f@kvLdn3h8~;)4ftekj3WN+UXaxPD!Qu2`Vu)b~7KI31cy_+#>G(bhrY zRzx8(p7S%AtCBoyJ`E5h!BrLQw*;buOU;di1<(?H6Z;!3iGsXcj{ z>tXVAZ^QlVJ{@Z#n73mYRwIx3A&ot9mlsN+4 zQ1RjA0I7*LgabcEaRNJw@!2h>u&2#!IaWhm{?`>$i$2$Z!!56Fcmq>2xVbBhvVf*)n1!l( z$otBpqKdFH(0jC3*9Rmlp2efr))eeX*5>w6%=~j9>ctED^YxdL?VtQXLB}UwPm<-X zw0Gur@+bfBa1tNY(kcU%vadC&3^t@e$JRok7oy}`|1}1Lctf3%5N~D?wm7kw!C|KX zIVFSlgbbvOdtpH;bNB4iSt6gs|wJskev^8V(M9e$qrlOZg37{$87pWdhS=A#k|RBse2;Rt~ad^I1;& zj37hoF?!)_{v$RutfI(hSe0qm8If@0OHUx47V#xc6*@I~)k|(54g6{7kFnRe$(w|0 zGse6ChGU&DncF+1R8DbKos4upY(77qraHdF+5jl*aA4JGoP=mEylV$`OSrb;9hid6Zhga%+RnPLOi)8Z*|P%A{f& z=u2`(27p^)lChzgMksy1mlJP`aHQ50L^^ZmYm?e-NA4W^g6`M9=NtFd)z%SgTI&d$ zl;2e_w{lFS%C_$4(vj2}khf^E+cL*f1%h4)I+7IB(i@!f(bI1~FYOB^mf!gvc0R(d z3+0a*GRmjzc^SRJSFCEk?^;O?<7#o=&bGc%=RXfxu0Go88)4<YLNbUeOXTwB@Gh!y|9 zs(tj5k2>lMLnYDr;$5gV7WS@pRGpTH&>m+Y3qipQNkV+e^parLP-jJl=mUgH-&age z3v^sq+H>#xA}ns>y7rp`ff5e0FKVMdW^8{x+V|&yd z_xR<}54vXboiOuk1O9CW?h)_x5nXSv;(e!mKi4<9FSEJLDH<_lpI+5KRK zJX=Ysmiy?QEZX{fhk(S_A5CoJ#JF^l@CSp`8O-d)7Jw&Y)EE)|PPjKm_%H+b6?23I z8+%Z{(Rf|GF6gV~c%)KCP5pDtr_ENzt*^Um+J}K$|;G$6wE+Uh8;p6Hs@K- z_oA&%C>a92$unKH+etsvV8o^B3MVaH{J&OjAWAn9<+!tqBbwqvEikWAG;YgW$#n=r z7XIAc*l&5n#imNwo%?Rg?9th6s9*$bzU-l`T28q{8vpsWHzpbWWLkB}?=gB}-*_%M z7#4J}9L;g_i9^Fw223qfKDkmKa3kNmU>#iE2`?GWOSkz-h?&P@-60)B7jF8vRT zf4@jAm2kLIpea0#S}9M=)esiEZT3uP_0PE~>b7+V2=L}Vbc|{S$!=>a1XcY<27 zuv<9-BA5+-u$7-Tr@uv9wFysc7P4jT$?D(p@o`F&2-OfYn@?@^aXX@{r2q#3;&fo;R_Li>uujbKIg(|dindrwS({f@WL z@?#qFriDD-H>L#J#_JqXb5bFko&%)g(0!!Bb>9z@awsjYT(<4qtLYoWecUqvy`rr` zO*!A+836{JhU|*ZLtWv;ijW$580=t$vfD(KW#$ z-)7lBa!`)${|<;8IU2;x%#V+=>;Cz0xZ;rFao1h;d*q|~@qo&V%iAs~f#^0l>qU#% z3>UII@QhHz`ie6RxKohwp*o)N#g9p-Ibmq)ppFdtetr+(5?mNvG*J>1;%X!C0(A#& zMp*a9{d#z1_VeKD*X6RmfQqdE4%O{`Y`AO20Y!-fzLmLQpBtpn)zR&oH^Sn{W;yo3 zbx!SMR?o8sbVa!9u~SV^>zkmd`bi1WW|lWBX?MMPe{t0@jw~|BGQr|Zi(0vdAAlW{ zA(Yp5(?p@Bgkc7F-k$tHb#Kj5d7@lglGv1VqQ2Wkvorb&C1$2Lb-jlnPh`BF@pqlH ze`n~-KJO=Z*99A2KZ74L4dnlR{Sb5yf>7Mwk(ye8lzGN7_Kav*%EzrTI63 z=L4l1k4wM#pQM^whYY5t@J=$K>}bWF%@;C`FNWr-S0;sQ2748BE!>X>r-LgHvE;{% zZ6YuUTnmgTeE+hOlMZ7Qfq;1(N*Ke;jV4t6z{5;wedxX5PT4!%6^mp;m0#+GygY5| zYTytm#cLMZ{6PRSGS*=R`g5rdy8IWFP6L^fwV&90m*uCuu7QrR<; zHA=7=Zr>Zv#o*+~qsn2fr2A(i$a0JRhL>B_PDdLFa9$TWtscc@d>L`MNtq}$uBfQ^ zc3gEYR$nI5q7vPc zIK6i>2kF9z@O0oLV;?%c29!%9J(ZZ#cdVuje@mD_fllpps8I?=dGtXt=K>2^;)=+& zYHYR+>{=V^$Gr|u3{jSvm>jkLx%}YX*GE*TYXFy<4dOzp3m2sMCnWEmuli8(`qgLS z%eDiyb`rQ)_jmFPa}gVB?Zt;JXC!j2L5i-Z@|UxZmhl_1dOlmgld*er-^UqL$CF+8 z6-E+^$;72WPid!#<_Dw_Yi&>w{_a58tFua!nSW@&v^VwOziN< zDMh5;_afTUW|8W6--@0N2ej-^UA1z92uonB`{RWXX;b!{F07)|q@3hQrd}w^@1Im) zaJD|bj?sAm)H zWYj6zcaHbO*k!h>8*hIjOVCEee4bV)_!Y;~il~kT$oi7pzb#GuqvA$bpmK`lgeP$H z{@sBeVB@~sUV$?%6fJqoa8I zsEAKy+cizBYFMro&SkNOk}fDwh+A1^-pS#oZNtx86%Xd_DSisi7|*gigF~Oo zub6p-5_6GrZG}WM*Wb&9b19Ace7u1SyJdnK(JrF?;nj1Ym~Q(}Btv4FSSachD0NL541I_%GTIOGz)8*V2~1ND6<9d&0EH3Sj%;FR;`~XyVVt@Vimv z*Tebj)_`mZ@gy$hH;j?u@@P#>eni3Q7e=;TS^ae5vfj3vQ@2K7i}5l6c_73yM~D!v*$*J`LCeO-4JshaLKXTkct_$c_%1}SZn6q7ZTU5y@BFVG z3U~4o-bk#-u){su_WM1vufDo7{@P2h{R20`0ML;>8+P5pOTVA}n+|3FM^gP7^#31b dw3|-f2CSbj(BrHf!|f7&%uQ{slwWp#@;{Rp>s9~& literal 62182 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�P z$1>QR&^abSi*y6Cl3fAm#cZdJ+^tPG)j@^8(As;A>bRV*c>i;f=fg{GEJr9N&MYFI zwLG;;#FVi;H3F_TvHH&@uKpb4kj3jV{mhevfqM1SiqeB7;{D7=_=9oY#d*fzEV&DA z5AUp)vIX}kXv^tq!J@LRj9#y8cM${CSxT$uPUc0f@9Vo^AL!q-*&_m)1mDgi`ZgC8 zJ2=HFE(Sks&S*>7Be7qy-5Plw6?2y%7FBQsR_@sD`tpLSoBoMDDoHi`l3}>?OwFMv z&oFFPu3}0rd^Qg?0!d5HO$b-GByqo`lT*)e;I5N8tgPfGW2-t7Ssu^%{xY-d4Z*}g zVf?y-sENf=L1|&oVx^(ZeB1qtr3uJXj(o(l%N2UfPYY+lo}AUZpI|`-6hlwHMHAlr z95p7~-(P9YL0bw!?o zIzV#+fWN+)`2UcIf8J1k9Q@N;|2TG({XZ{2=507-GM&&r-G|(we^4J-HMIG=5@+oR z2fg6c%vkD!=}7f4=n3Voc2@;J&pAQZUj>UDvoOkGoNtzT(6Kw5q$FUJUWK&2gp(}7 zO4TLbRB)Nj1ua|(Nb6JkPqnnplDXp5{(B}h`eMnxO61df6n0;tv-?Zi*iRZ`+huF% z|IP|p54e9_bJPRdC4NV&CO^kAjGE$!Ki~OiQh{MUhB(z8nAY3%aoc}G%m>dqa#mCx?FyuxEqG1v-e+b6u)s)6GY8` z>wAmwg;X)d(g&)H`Y`W101GfavOB)CkjA&?XI@ zD+BmNxG%$b92`tiuOe#zJhrx&YQC$tHNuCi{UT@zaA)y%ZjcdSl-uAs?PiO6E*ZX< zruJNCB6n2*t;R&1C;}GT& z{i|qiu7&H%AmU+ZJ$=`mBB`UwIGhG7)yUf%_bsASYJ%zqJFzAm=|Cw#L>L}Sc8A!@ z4%jIaNU3@7HOS7XS&nz{PuX}qgt`TJYZ9$qtf=FB;}$Ei+}(wbJ0?f{^q(e~YAls* z&CmSG->h&b*=up(LrIqV)_Rhs%#`cr5sA*yzGd7!MUkCS4+CL!`lp{G3VV*a%LG|D zz%9qWdc3b3mIGIBdkeb|NhPvx44x!VYU8GcihezyWZToF4tK+o6MvL?)QD^zJ`=%h z8DedT5yT`B2j)?N_{1&8<7t+ga>de zF~sDx)Z(r2;}jXq98A!;kSl&|B;uw5+7_Jc1wA<0MRLyo=DYF zDD~DqeIkmk!Mx->k}mfG+0L-+3tY?oWz;uu;f~}Bn>a!&;rn=%lUL&9`0$|zvYXjg zpL3Zw=$9M)^;s@rI*dT<$UF%XwmHziH@rMdD_75&AMUJkm+>%@(9o zdmBNji`~d4Jg?|j@k*N0iL{#se5AtW-9$9&v{cXmzkJKzE7JX-y%28F%Np~*?eJ9( z73rezkzT0fuS#{<6N16p#TM%7P$Xk1?Io?1uiSc%iyiTNC%KCvJO=;uMl*}SVAT-X z_?w$4FKHd( Date: Tue, 12 Mar 2024 17:07:58 -0700 Subject: [PATCH 30/37] Bump the version in compatibility matrix. --- developer_resources/compatibility_matrix.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/developer_resources/compatibility_matrix.md b/developer_resources/compatibility_matrix.md index e24bf976..b3b87353 100644 --- a/developer_resources/compatibility_matrix.md +++ b/developer_resources/compatibility_matrix.md @@ -11,7 +11,8 @@ The URBANopt™ installer includes Ruby and OpenStudio. The matri |URBANopt Version|OpenStudio| OpenStudio-HPXML | ResStock | Ruby | Python | REopt API | Modelica Buildings Library | |:--------------:|:--------:|:----------------:|:--------:|:----:|:------:|:---------:|:--------------------------:| -| 0.11.0 | 3.7.0 | 1.7.0 | 3.2.0 | 2.7.2| 3.10 | v2 | 10 | +| 1.0.0 | 3.7.0 | 1.7.0 | 3.2.0 | 2.7.2| 3.10 | v2 | 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 | From effdfd2c5d77141fef55a0501764b6f8001a2a43 Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Wed, 15 May 2024 10:02:53 -0600 Subject: [PATCH 31/37] update compatibility matrix --- developer_resources/compatibility_matrix.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/developer_resources/compatibility_matrix.md b/developer_resources/compatibility_matrix.md index c9440071..a4549c57 100644 --- a/developer_resources/compatibility_matrix.md +++ b/developer_resources/compatibility_matrix.md @@ -11,6 +11,7 @@ The URBANopt™ installer includes Ruby and OpenStudio. The matri |URBANopt Version|OpenStudio| OpenStudio-HPXML | Ruby | Python | REopt API | Modelica Buildings Library | |:--------------:|:--------:|:----------------:|:----:|:------:|:---------:|:--------------------------:| +| 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 | @@ -29,7 +30,8 @@ URBANopt™ depends on various other components to function. Ensu |URBANopt Version|URBANopt CLI|OpenStudio|Ruby |Gems | |:--------------:|:----------:|:--------:|:-----:|:------------------------------------| -|**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.3 **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.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 | From d32796cd38e2e4f24ef8194d23ebf5eac2e4376b Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Wed, 15 May 2024 10:12:06 -0600 Subject: [PATCH 32/37] update release instructions to match current practice --- developer_resources/release_instructions.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) 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: From 178a84fb875ca779b40311d92d9011c7b307441b Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Tue, 21 May 2024 10:43:15 -0700 Subject: [PATCH 33/37] Attempt to make distinct between connection paths. --- .../residential_workflows/building_inputs.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/workflows/residential_workflows/building_inputs.md b/workflows/residential_workflows/building_inputs.md index da97e20b..5ee4dcf1 100644 --- a/workflows/residential_workflows/building_inputs.md +++ b/workflows/residential_workflows/building_inputs.md @@ -86,9 +86,13 @@ Users should ensure that specific assumptions in their templates are accurate fo ### ResStock Samples -As of v1.0.0, optional boolean and path fields may be set in GeoJSON features to indicate assignment of argument values corresponding to ResStock dwelling unit samples. +As of v1.0.0, optional boolean and path fields may be set in GeoJSON features to indicate assignment of argument values corresponding to mapped ResStock parameters. See a [GeoJSON Schema](building_types#geojson-schema) optional fields section for specific boolean and path field names. -The path field should be a relative file path that references a sampled ResStock **buildstock CSV file**. +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. @@ -96,14 +100,18 @@ Each sample (i.e., row of the buildstock CSV file) represents several individual 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. +- [ResStockArguments](https://github.com/NREL/resstock/tree/develop/measures/ResStockArguments) OpenStudio measure -Each row of the buildstock CSV file, therefore, becomes a representative building model created from mapped model input values. +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 matching buildstock CSV file sample row(s) to GeoJSON feature properties (e.g., building type, number of stories, floor area). +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. From df248a461ccc73d28e799e15e7ace3f10c8d6f04 Mon Sep 17 00:00:00 2001 From: Nathan Moore Date: Fri, 24 May 2024 11:19:40 -0600 Subject: [PATCH 34/37] add missing and new publications --- resources/publications.md | 25 ++++++++++++++++++++++++- workflows/des.md | 2 +- 2 files changed, 25 insertions(+), 2 deletions(-) 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/des.md b/workflows/des.md index 81e54514..d9d25f53 100644 --- a/workflows/des.md +++ b/workflows/des.md @@ -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. From 13c70ac9ac8e68b4fd69fd8c3fc0fe5b886fa624 Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Thu, 30 May 2024 11:51:50 -0700 Subject: [PATCH 35/37] Further reorganize and simplify the residential sections. --- _site/index.html | 2 +- .../residential_workflows/building_inputs.md | 4 +- .../residential_workflows/building_types.md | 131 +----------------- .../other_assumptions.md | 58 -------- .../residential_workflows/other_details.md | 97 +++++++++++++ .../residential_workflows.md | 4 +- 6 files changed, 108 insertions(+), 188 deletions(-) delete mode 100644 workflows/residential_workflows/other_assumptions.md create mode 100644 workflows/residential_workflows/other_details.md diff --git a/_site/index.html b/_site/index.html index 5f7a38ea..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-2024, 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/workflows/residential_workflows/building_inputs.md b/workflows/residential_workflows/building_inputs.md index 5ee4dcf1..4ac9289a 100644 --- a/workflows/residential_workflows/building_inputs.md +++ b/workflows/residential_workflows/building_inputs.md @@ -33,7 +33,7 @@ The air leakage infiltration rate of the building may be changed from its defaul ### Customizable Template An optional template enumeration may be specified for each feature in the GeoJSON file. -See a [GeoJSON Schema](building_types#geojson-schema) optional fields section for the specific template field name. +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: @@ -87,7 +87,7 @@ Users should ensure that specific assumptions in their templates are accurate fo ### ResStock Samples As of v1.0.0, optional boolean and path fields may be set in GeoJSON features to indicate assignment of argument values corresponding to mapped ResStock parameters. -See a [GeoJSON Schema](building_types#geojson-schema) optional fields section for specific boolean and path field names. +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 diff --git a/workflows/residential_workflows/building_types.md b/workflows/residential_workflows/building_types.md index 70c575d1..08aa1cf4 100644 --- a/workflows/residential_workflows/building_types.md +++ b/workflows/residential_workflows/building_types.md @@ -38,54 +38,14 @@ 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](other_assumptions.md) for more information. +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) -#### 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. - - 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. - -#### 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: - -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_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 | | -| onsite_parking_fraction | number | (1) No (0)
(2) Yes (1) | | -| hpxml_directory | string | | Relative to xml_building. Most required fields are then 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) | - An example "Single-Family Detached" building feature snippet is shown below. ```json @@ -132,53 +92,14 @@ You can see outside boundary conditions of "Outdoors" on one facade, and "Adiaba ![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](other_assumptions.md) for more information. +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) -#### 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 | | -| hpxml_directory | string | | Relative to xml_building. Most required fields are then optional. | -| template | string | | See [Customizable Template](argument_values.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) | - An example "Single-Family Attached" building feature snippet is shown below. ```json @@ -225,54 +146,14 @@ You can see outside boundary conditions of "Outdoors" on the roof and one facade ![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](other_assumptions.md) for more information. +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) -#### 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 | | -| hpxml_directory | string | | Relative to xml_building. Most required fields are then optional. | -| template | string | | See [Customizable Template](argument_values.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) | - An example "Low-Rise Multifamily" building feature snippet is shown below. ```json diff --git a/workflows/residential_workflows/other_assumptions.md b/workflows/residential_workflows/other_assumptions.md deleted file mode 100644 index 858052fd..00000000 --- a/workflows/residential_workflows/other_assumptions.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -layout: default -title: Other Assumptions -parent: Residential Workflows -grand_parent: Workflows -nav_order: 4 ---- - -## Other Assumptions - -Other assumptions are made for the following categories: - -- [Geometry](#geometry) -- [Fuel Types](#fuel-types) - -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. \ No newline at end of file diff --git a/workflows/residential_workflows/other_details.md b/workflows/residential_workflows/other_details.md new file mode 100644 index 00000000..0cf7e803 --- /dev/null +++ b/workflows/residential_workflows/other_details.md @@ -0,0 +1,97 @@ +--- +layout: default +title: Other Details +parent: Residential Workflows +grand_parent: Workflows +nav_order: 4 +--- + +## Other Details + +Other modeling details are described for the following categories: + +- [Modeling Notes](#modeling-notes) +- [GeoJSON Schema](#geojson-schema) +- [Assumptions](#assumptions) + +### Modeling Notes + +- 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 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, Single-Family Attached, and Low-Rise Multifamily residential buildings. + +**Required** fields: + +| 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 | 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: + +| 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 | | +| 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 93c551d0..b7f8088d 100644 --- a/workflows/residential_workflows/residential_workflows.md +++ b/workflows/residential_workflows/residential_workflows.md @@ -20,7 +20,7 @@ In the case of a multifamily building one HPXML file is built containing multipl The following sections describe the types of buildings supported by this workflow and how input values are assigned to various arguments. -- [Building Types](building_types.md) lists the supported residential building types, including modeling notes and GeoJSON schema details. +- [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 Assumptions](other_assumptions.md) describes modeling assumptions related to geometry and fuel types. +- [Other Details](other_details.md) describes modeling notes, GeoJSON schema details, and assumptions related to geometry and fuel types. From dce4d291063aef01e90a3707dfc8b34b4f1a170b Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Mon, 24 Jun 2024 08:46:58 -0700 Subject: [PATCH 36/37] Switch 1.0.0 to 0.13.0 in compatibility matrix. --- developer_resources/compatibility_matrix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer_resources/compatibility_matrix.md b/developer_resources/compatibility_matrix.md index 14d54173..5cbe7944 100644 --- a/developer_resources/compatibility_matrix.md +++ b/developer_resources/compatibility_matrix.md @@ -11,7 +11,7 @@ The URBANopt™ installer includes Ruby and OpenStudio. The matri |URBANopt Version|OpenStudio| OpenStudio-HPXML | ResStock | Ruby | Python | REopt API | Modelica Buildings Library | |:--------------:|:--------:|:----------------:|:--------:|:----:|:------:|:---------:|:--------------------------:| -| 1.0.0 | 3.7.0 | 1.7.0 | 3.2.0 | 2.7.2| 3.10 | v2 | 10 | +| 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 | From 492c5aa0ef03cd17b75fbf092a9a73046ef2e7e2 Mon Sep 17 00:00:00 2001 From: kflemin <2205659+kflemin@users.noreply.github.com> Date: Thu, 27 Jun 2024 15:32:57 -0600 Subject: [PATCH 37/37] update cli version number --- workflows/residential_workflows/building_inputs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/workflows/residential_workflows/building_inputs.md b/workflows/residential_workflows/building_inputs.md index 4ac9289a..fd6e8802 100644 --- a/workflows/residential_workflows/building_inputs.md +++ b/workflows/residential_workflows/building_inputs.md @@ -86,7 +86,7 @@ Users should ensure that specific assumptions in their templates are accurate fo ### ResStock Samples -As of v1.0.0, optional boolean and path fields may be set in GeoJSON features to indicate assignment of argument values corresponding to mapped ResStock parameters. +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: