From 158396a83139910a537dafae05633ce6426dc067 Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Wed, 6 Mar 2024 14:15:40 -0700 Subject: [PATCH 01/13] 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 02/13] 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 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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(© 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 03/13] 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 04/13] 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 05/13] 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 06/13] 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 07/13] 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 08/13] 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 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 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( Date: Tue, 12 Mar 2024 17:07:58 -0700 Subject: [PATCH 09/13] 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 178a84fb875ca779b40311d92d9011c7b307441b Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Tue, 21 May 2024 10:43:15 -0700 Subject: [PATCH 10/13] 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 13c70ac9ac8e68b4fd69fd8c3fc0fe5b886fa624 Mon Sep 17 00:00:00 2001 From: Joe Robertson Date: Thu, 30 May 2024 11:51:50 -0700 Subject: [PATCH 11/13] 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 12/13] 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 13/13] 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: