diff --git a/_site/index.html b/_site/index.html index 5d1e5e7d..5edd58a6 100644 --- a/_site/index.html +++ b/_site/index.html @@ -1 +1 @@ - Home - URBANopt Docs Home | [“URBANopt Docs”] Link Search Menu Expand Document

urbanopt logo

URBANopt SDK Documentation

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

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

graphic showing urbanopt at a high level

Use Cases

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

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

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

main urbanopt capabilities

click to expand image

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

uo ecosystem diagram

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

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

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

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

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

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

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

urbanopt logo

URBANopt SDK Documentation

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

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

graphic showing urbanopt at a high level

Use Cases

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

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

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

main urbanopt capabilities

click to expand image

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

uo ecosystem diagram

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

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

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

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

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

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

diff --git a/developer_resources/compatibility_matrix.md b/developer_resources/compatibility_matrix.md index a4549c57..5cbe7944 100644 --- a/developer_resources/compatibility_matrix.md +++ b/developer_resources/compatibility_matrix.md @@ -9,19 +9,20 @@ 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.12.0 | 3.7.0 | 1.7.0 | 2.7.2| 3.10 | v3 | 10 | -| 0.11.0 | 3.7.0 | 1.7.0 | 2.7.2| 3.10 | v2 | 10 | -| 0.10.0 | 3.6.1 | 1.6.0 | 2.7 | 3.10 | v2 | 9 | -| 0.9.1 - 0.9.2 | 3.5.1 | 1.5.1 | 2.7 | 3.10 | v2 | 9 | -| 0.9.0 | 3.5.0 | 1.5.0 | 2.7 | 3.10 | v2 | 9 | -| 0.8.0 - 0.8.2 | 3.4.0 | 1.4.0 | 2.7 | 3.7 | v1 | 8 | -| 0.7.0 - 0.7.1 | 3.3.0 | 1.3.0 | 2.7 | 3.7 | v1 | 7 | -| 0.6.0 - 0.6.4 | 3.2.0 | 1.2.0 | 2.7 | 3.7 | v1 | 7 | -| 0.5.0 - 0.5.1 | 3.1.0 | 1.1.0 | 2.5 | 3.7 | v1 | -| 0.4.0 - 0.4.1 | 3.0.1 | - | 2.5 | 3.7 | v1 | -| 0.3.1 | 3.0.1 | - | 2.5 | 3.7 | v1 | +|URBANopt Version|OpenStudio| OpenStudio-HPXML | ResStock | Ruby | Python | REopt API | Modelica Buildings Library | +|:--------------:|:--------:|:----------------:|:--------:|:----:|:------:|:---------:|:--------------------------:| +| 0.13.0 | 3.7.0 | 1.7.0 | 3.2.0 | 2.7.2| 3.10 | v2 | 10 | +| 0.12.0 | 3.7.0 | 1.7.0 | - | 2.7.2| 3.10 | v3 | 10 | +| 0.11.0 | 3.7.0 | 1.7.0 | - | 2.7.2| 3.10 | v2 | 10 | +| 0.10.0 | 3.6.1 | 1.6.0 | - | 2.7 | 3.10 | v2 | 9 | +| 0.9.1 - 0.9.2 | 3.5.1 | 1.5.1 | - | 2.7 | 3.10 | v2 | 9 | +| 0.9.0 | 3.5.0 | 1.5.0 | - | 2.7 | 3.10 | v2 | 9 | +| 0.8.0 - 0.8.2 | 3.4.0 | 1.4.0 | - | 2.7 | 3.7 | v1 | 8 | +| 0.7.0 - 0.7.1 | 3.3.0 | 1.3.0 | - | 2.7 | 3.7 | v1 | 7 | +| 0.6.0 - 0.6.4 | 3.2.0 | 1.2.0 | - | 2.7 | 3.7 | v1 | 7 | +| 0.5.0 - 0.5.1 | 3.1.0 | 1.1.0 | - | 2.5 | 3.7 | v1 | - | +| 0.4.0 - 0.4.1 | 3.0.1 | - | - | 2.5 | 3.7 | v1 | - | +| 0.3.1 | 3.0.1 | - | - | 2.5 | 3.7 | v1 | - | ## URBANopt Compatibility Matrix diff --git a/doc_files/os-hpxml-resstock-workflow.png b/doc_files/os-hpxml-resstock-workflow.png new file mode 100644 index 00000000..870ca4dc Binary files /dev/null and b/doc_files/os-hpxml-resstock-workflow.png differ diff --git a/workflows/residential_workflows/building_inputs.md b/workflows/residential_workflows/building_inputs.md new file mode 100644 index 00000000..fd6e8802 --- /dev/null +++ b/workflows/residential_workflows/building_inputs.md @@ -0,0 +1,134 @@ +--- +layout: default +title: Building Inputs +parent: Residential Workflows +grand_parent: Workflows +nav_order: 2 +--- + +## Building Inputs + +HPXML files are built based on feature information contained in the GeoJSON file. +The [Building Types](building_types.md) section lists all the required and optional GeoJSON fields for each building type. + +Following the assignment of fields from the GeoJSON file (e.g., building type, number of stories, floor area), a number of inputs are defaulted using the OpenStudio-HPXML workflow. +Optionally, input values may be *further* refined/adjusted using either a customizable template or samples from the [ResStock™](https://www.nrel.gov/buildings/resstock.html) workflow. + +- [Default Values](#default-values) +- [Customizable Template](#customizable-template) +- [ResStock Samples](#resstock-samples) + +After all arguments are assigned input values and an HPXML file is built, a translator measure is then applied to construct an OpenStudio© building model. + +### Default Values + +The [Input Defaults](https://openstudio-hpxml.readthedocs.io/en/latest/workflow_inputs.html#input-defaults) section of the [OpenStudio-HPXML documentation](https://openstudio-hpxml.readthedocs.io/en/latest/index.html) describes how HPXML fields may be defaulted. +Defaults are generally based on **ANSI / RESNET / ICC Std. 301 (2019)**. + +For example, the air leakage infiltration rate of the building (i.e., air changes per hour at 50 Pascals obtained from a blower door measurement) is not specified using feature information from the GeoJSON file. +A default value of 3 ACH50 is used, which impacts the infiltration model. + +The air leakage infiltration rate of the building may be changed from its default value of 3 ACH50 (e.g., to 7 ACH50 or 20 ACH50) using either approach described in the following [Customizable Template](#customizable-template) and [ResStock Samples](#resstock-samples) sections. + +### Customizable Template + +An optional template enumeration may be specified for each feature in the GeoJSON file. +See the [GeoJSON Schema](other_details#geojson-schema) optional fields section for the specific template field name. +The assignment of various argument values contained in *TSV lookup files* depend on the specified template enumeration. +Customizable template enumerations that are applicable to residential buildings: + +- `Residential IECC - Customizable Template Sep 2020` +- `Residential IECC - Customizable Template Apr 2022` + +for ` = 2006, 2009, 2012, 2015, 2018`. + +The various arguments that may be assigned input values use mappings contained in the following [TSV lookup files](https://github.com/urbanopt/urbanopt-example-geojson-project/tree/develop/example_project/mappers/residential/template/iecc): + +- clothes_dryer.tsv +- clothes_washer.tsv +- cooling_system.tsv +- dishwasher.tsv +- enclosure.tsv +- heat_pump.tsv +- heating_system.tsv +- mechanical_ventilation.tsv +- refrigerator.tsv +- water_heater.tsv + +Argument values found in these lookup files span across the following categories: + +- enclosure (insulation levels, air leakage, etc.) +- heating/cooling systems (types, efficiencies, etc.) +- appliances (refrigerator, clothes washer, etc.) +- mechanical ventilation +- water heating + +All argument values for the previous categories may be customized by manually adjusting values in the lookup files, or a new customizable template with unique argument values may be created as described below. +The enumeration names include "Residential IECC 20XX" because a variety of enclosure, window, duct insulation, and whole-home air leakage assumptions are based on the different IECC model code years to illustrate how templates can be used to approximate different levels of efficiency. +Note that not all possible assumptions have been aligned with IECC requirements (e.g., see above regarding defaults), but the users can further customize these templates as needed for specific projects. + +The residential workflows in URBANopt are designed to be flexible and extensible to adapt to specific user projects. +The building models are created on the basis of default assumptions made for different building components within lookup files, grouped together within a template, and assigned to the building feature in the feature file. +To modify the models, these templates and the underlying assumptions can be customized, or a new template with unique assumptions can be created. +The URBANopt example project includes alternate customizable "Residential IECC 20XX - Customizable Template Apr 2022" templates (e.g., for modeling homes where some types appliances are not present and/or efficiency of certain appliances/equipment needs to be adjusted) and illustrates how these could be assigned to the building features. + +The specific assumptions made in these customized templates for different building equipment in the lookup files are: + +- Clothes Dryer: The location is updated to be "none" and it is assumed that no clothes dryer is present. +- Clothes Washer: The location is updated to be "none" and it is assumed that no clothes dryer is present. +- Dishwasher: The location is updated to be "none" and it is assumed that no clothes dryer is present. +- Refrigerator: The efficiency of the appliance is modified. +- Water heater: The efficiency of the appliance is modified. + +This customized template is assigned to the low-rise residential building features in the [alternate combined example project feature file](https://github.com/urbanopt/urbanopt-cli/blob/e7d29764eb9ae837078f92a488adb783a3e52616/example_files/example_project_combined.json). +It is to be noted that these values are meant to be representative to illustrate how templates can be used to customize the workflow for different communities and are not based on an actual community or formal study. +Users should ensure that specific assumptions in their templates are accurate for the homes/communities they are modeling. + +### ResStock Samples + +As of v0.13.0, optional boolean and path fields may be set in GeoJSON features to indicate assignment of argument values corresponding to mapped ResStock parameters. +See the [GeoJSON Schema](other_details#geojson-schema) optional fields section for specific boolean and path field names. +The path field should be either a: + +- relative file path that references a ResStock **buildstock CSV file** directly sampled from a project, or +- relative file path that references a ResStock **buildstock CSV file** mapping GeoJSON feature ID to set of ResStock parameters. + +The buildstock CSV file stores a collection of Parameter/Option pairs, organized by ResStock Building ID, that have been sampled from a set of statistical distributions derived from U.S. residential housing stock characterization data. +An example of a buildstock CSV file is given [here](https://github.com/NREL/resstock/blob/develop/test/base_results/baseline/annual/buildstock.csv). +Each sample (i.e., row of the buildstock CSV file) represents several individual dwelling units within the actual housing stock. + +ResStock maps individual dwelling unit samples into OpenStudio-HPXML argument values using the: + +- [options_lookup.tsv](https://github.com/NREL/resstock/blob/develop/resources/options_lookup.tsv) file +- [ResStockArguments](https://github.com/NREL/resstock/tree/develop/measures/ResStockArguments) OpenStudio measure + +Each row of the buildstock CSV file, therefore, becomes a building model created from mapped model input values. +The basic OpenStudio-HPXML/ResStock/URBANopt workflow is depicted in the flow chart below. + +![os-hpxml-resstock-workflow](../../doc_files/os-hpxml-resstock-workflow.png) + +URBANopt connects to ResStock by either: + +- matching sampled buildstock CSV file sample row(s) to GeoJSON feature properties (e.g., building type, number of stories, floor area), or +- matching the row of the buildstock CSV file by GeoJSON feature ID + +Once the appropriate ResStock Building ID from the buildstock CSV file is identified, argument values corresponding to sampled Parameter/Option pairs can be assigned. +Note that some argument assignments from the options_lookup.tsv file are ignored if they conflict with defined properties in the GeoJSON feature. +For example, the "County" parameter maps various weather-related arguments, but location is already defined in the GeoJSON file. + +Previously defaulted input values are thus refined using argument value assignments corresponding to representative ResStock samples. +In the case of the air leakage infiltration rate example from above, ResStock explicitly samples "ACH50" options for its "Infiltration" parameter. +If the identified ResStock Building ID has a corresponding sampled "7 ACH50" option, this would result in overriding the default value of 3 ACH50 with 7 ACH50. +The [Housing Characteristics](https://resstock.readthedocs.io/en/latest/workflow_inputs/characteristics.html#housing-characteristics) section of the [ResStock documentation](https://resstock.readthedocs.io/en/latest/index.html) describes all parameters sampled by ResStock. + +ResStock samples are defined at the individual dwelling unit level. +Therefore, with the exception of stochastic occupancy schedules, this workflow duplicates dwelling units for Single-Family Attached and Low-Rise Multifamily buildings. +Building units have variation across schedules but not in terms of their: + +- attic type (e.g., vented, adiabatic) +- foundation type (e.g., slab, adiabatic) +- orientation (e.g., North, South) +- location (e.g., corner unit, top unit) + +After each feature's HPXML file is built (containing 1 or more dwelling units), OpenStudio-HPXML's [HPXMLtoOpenStudio](https://github.com/NREL/OpenStudio-HPXML/tree/master/HPXMLtoOpenStudio) OpenStudio measure is applied to translate and construct an OpenStudio building model. +The building model is then simulated using OpenStudio/EnergyPlus. diff --git a/workflows/residential_workflows/building_occupancy.md b/workflows/residential_workflows/building_occupancy.md new file mode 100644 index 00000000..69af5559 --- /dev/null +++ b/workflows/residential_workflows/building_occupancy.md @@ -0,0 +1,40 @@ +--- +layout: default +title: Building Occupancy +parent: Residential Workflows +grand_parent: Workflows +nav_order: 3 +--- + +## Building Occupancy + +The user has control over both occupant-related schedule types and occupancy calculation types: + +- [Schedule Types](#schedule-types) +- [Calculation Types](#calculation-types) + +### Schedule Types + +Occupant-related schedules can be either defaulted (smooth) or stochastically generated, and may vary either building-to-building or unit-to-unit. +The default behavior is to use stochastically generated schedules that vary unit-to-unit, but the user has control to both use defaulted schedules and vary them building-to-building. +Note that there are runtime impacts associated with using stochastically generated schedules and for varying schedules unit-to-unit. + +Stochastic schedules are generated using time-inhomogenous Markov chains derived from American Time Use Survey data, supplemented with sampling duration and power level from NEEA RBSA data, as well as DHW draw duration and flow rate data from Aquacraft/AWWA data. + +In terms of repeatability, stochastic schedules generation uses a pseudo-random number generator that takes a seed as an argument. +The seed is determined by the index of a given feature relative to all features in the GeoJSON, and then multiplied by the unit number within the building. +For schedules that vary by building, the schedules that correspond to the first unit are used for all units of the building. +Relocating a feature's position within a GeoJSON would change the seed argument for that building. + +### Calculation Types + +Occupancy-based loads (i.e., plug loads, appliances, hot water, etc.) can be calculated through either: + +1. an asset calculation, or +1. an operational calculation. + +The default behavior is to perform an asset calculation, but the user has control to enable an operational calculation. + +Asset calculations are performed using number of bedrooms and/or conditioned floor area. + +Operational calculations are performed using an adjustment for the number of occupants. \ No newline at end of file diff --git a/workflows/residential_workflows/building_types.md b/workflows/residential_workflows/building_types.md new file mode 100644 index 00000000..08aa1cf4 --- /dev/null +++ b/workflows/residential_workflows/building_types.md @@ -0,0 +1,179 @@ +--- +layout: default +title: Building Types +parent: Residential Workflows +grand_parent: Workflows +has_children: true +nav_order: 1 +has_toc: false +--- + +## Building Types + +Currently, the following residential building types are supported: + +- [Single-Family Detached](#single-family-detached) +- [Single-Family Attached](#single-family-attached) +- [Low-Rise Multifamily](#low-rise-multifamily)[^1] + +Only the [Baseline Scenario](../../resources/scenarios/baseline.md) and [High Efficiency Scenario](../../resources/scenarios/highefficiency.md) are supported at this time; any additional mappers will need to be updated manually. + +Note that the modeling capabilities for these building types are currently in Beta mode. +This means that testing and development is still in progress, and user feedback is welcome. + +[^1]: Mid-Rise and High-Rise Multifamily building prototypes can be found in the commercial building workflows). + +### Single-Family Detached + +Consider the highlighted "Single-Family Detached" building footprint with the following high-level URBANopt™ GeoJSON inputs: + +* 1 story above ground +* unvented crawlspace foundation +* vented attic +* 2 car garage + +![single_family_detached](../../doc_files/single-family-detached-footprint.jpg) + +An example 3D rendering of the single-family detached building is shown below. + +![single_family_detached](../../doc_files/single-family-detached-1.jpg) + +Note that the footprint of the modeled unit, less the garage, is always rectangular even though the GeoJSON footprint may not be. +See [Assumptions](other_details#assumptions) for more information. + +The 3D building surfaces stored in HPXML and OSM models represent the area and orientation of ground and exterior exposure of surfaces, but do not represent their position relative to each other. +An example geometry rendering for a translated HPXML file is given below. + +![single_family_detached](../../doc_files/single-family-detached-2.jpg) + +An example "Single-Family Detached" building feature snippet is shown below. + + ```json + { + "type": "Feature", + "properties": { + "id": "14", + "name": "Residential 1", + "type": "Building", + "building_type": "Single-Family Detached", + "floor_area": 3055, + "footprint_area": 3055, + "number_of_stories_above_ground": 1, + "number_of_stories": 1, + "number_of_bedrooms": 3, + "foundation_type": "crawlspace - unvented", + "attic_type": "attic - vented", + "system_type": "Residential - furnace and central air conditioner", + "heating_system_fuel_type": "natural gas", + "onsite_parking_fraction": 1, + "template": "Residential IECC 2015 - Customizable Template Sep 2020" + } + ``` + +### Single-Family Attached + +Consider the highlighted "Single-Family Attached" building footprint with the following high-level URBANopt™ GeoJSON inputs: + +* 2 stories above ground +* slab foundation +* vented attic +* 4 living units +* no rear units + +![single_family_attached](../../doc_files/single-family-attached-footprint.jpg) + +The number of living units are used to determine the position (i.e., horizontal location) of individual living units contained in the building. +By determining the position of individual units relative the whole building, types and boundary conditions of surfaces (e.g., adiabatic) can be stored in the HPXML. + +Example 3D renderings for a single unit from the building is shown below. +This unit is designated as having a "Right" horizontal location (when viewing from the front). +You can see outside boundary conditions of "Outdoors" on one facade, and "Adiabatic" on the opposite facade. + +![single_family_attached](../../doc_files/single-family-attached-1-1.jpg) +![single_family_attached](../../doc_files/single-family-attached-1-2.jpg) + +Note that the footprint of the modeled unit is always rectangular even though the GeoJSON footprint may not be. +See [Assumptions](other_details#assumptions) for more information. + +For each unit of the building, an HPXML and OSM model is constructed. +These OSM models are merged into a single OSM model, as shown below. + +![single_family_attached](../../doc_files/single-family-attached-2.jpg) + +An example "Single-Family Attached" building feature snippet is shown below. + + ```json + { + "id": "17", + "name": "Residential 4", + "type": "Building", + "building_type": "Single-Family Attached", + "floor_area": 18320, + "footprint_area": 9160, + "number_of_stories_above_ground": 2, + "number_of_stories": 2, + "number_of_bedrooms": 6, + "foundation_type": "slab", + "attic_type": "attic - vented", + "system_type": "Residential - furnace and room air conditioner", + "heating_system_fuel_type": "fuel oil", + "number_of_residential_units": 4, + "template": "Residential IECC 2015 - Customizable Template Sep 2020" + } + ``` + +### Low-Rise Multifamily + +Consider the highlighted "Low-Rise Multifamily" building footprint with the following high-level URBANopt™ GeoJSON inputs: + +* 2 stories above ground +* slab foundation +* flat roof +* 8 living units +* double exterior corridor + +![multifamily](../../doc_files/multifamily-footprint.jpg) + +The number of living units and stories above ground are used to determine the position (i.e., horizontal location and vertical level) of individual living units contained in the building. +By determining the position of individual units relative the whole building, types and boundary conditions of surfaces (e.g., adiabatic) can be stored in the HPXML. + +Example 3D renderings for a single unit from the building is shown below. +This unit is designated as having a "Left" horizontal location and a "Top" vertical level (when viewing from the front). +You can see outside boundary conditions of "Outdoors" on the roof and one facade, and "Adiabatic" on the floor and opposite facade. + +![multifamily](../../doc_files/multifamily-1-1.jpg) +![multifamily](../../doc_files/multifamily-1-2.jpg) +![multifamily](../../doc_files/multifamily-1-3.jpg) +![multifamily](../../doc_files/multifamily-1-4.jpg) + +Note that the footprint of the modeled unit is always rectangular even though the GeoJSON footprint may not be. +See [Assumptions](other_details#assumptions) for more information. + +For each unit of the building, an HPXML and OSM model is constructed. +These OSM models are merged into a single OSM model, as shown below. + +![multifamily](../../doc_files/multifamily-2.jpg) + +An example "Low-Rise Multifamily" building feature snippet is shown below. + + ```json + { + "type": "Feature", + "properties": { + "id": "18", + "name": "Residential 5", + "type": "Building", + "building_type": "Multifamily", + "floor_area": 28636, + "footprint_area": 14318, + "number_of_stories_above_ground": 2, + "number_of_stories": 2, + "number_of_bedrooms": 16, + "foundation_type": "slab", + "attic_type": "flat roof", + "system_type": "Residential - furnace and room air conditioner", + "heating_system_fuel_type": "wood", + "number_of_residential_units": 8, + "template": "Residential IECC 2015 - Customizable Template Sep 2020" + } + ``` diff --git a/workflows/residential_workflows/customization.md b/workflows/residential_workflows/customization.md deleted file mode 100644 index da604baa..00000000 --- a/workflows/residential_workflows/customization.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -layout: default -title: Customization -parent: Residential Workflows -has_children: true -nav_order: 6 -has_toc: false ---- - -# Residential Workflows Customization - - -The residential workflows in URBANopt are designed to be flexible and extensible to adapt to specific user -projects. The building models are created on the basis of default assumptions -made for different building components within lookup files, grouped together within a template, and assigned to the -building feature in the feature file as described under [customizable template](https://docs.urbanopt.net/workflows/residential_workflows/residential_workflows.html#customizable-template). To modify the models, these templates and the underlying assumptions -can be customized, or a new template with unique assumptions can be created. The URBANopt example -project includes alternate customizable templates (e.g., for modeling homes where some types appliances are not present and/or efficiency of certain appliances/equipment needs to be adjusted) and illustrates how these could be assigned to the building features. - -The following additional customizable templates are included: - -- `Residential IECC 2006 - Customizable Template Apr 2022` -- `Residential IECC 2009 - Customizable Template Apr 2022` -- `Residential IECC 2012 - Customizable Template Apr 2022` -- `Residential IECC 2015 - Customizable Template Apr 2022` -- `Residential IECC 2018 - Customizable Template Apr 2022` - -The specific assumptions made in these customized templates for different building equipment in the -lookup files are: - -- Clothes Dryer : The location is updated to be 'none' and it is assumed that no clothes dryer is - present. - -- Clothes Washer: The location is updated to be 'none' and it is assumed that no clothes dryer is - present. - -- Dishwasher: The location is updated to be 'none' and it is assumed that no clothes dryer is - present. - -- Refrigerator: The efficiency of the appliance is modified. - -- Water heater: The efficiency of the appliance is modified. - -This customized template is assigned to the low-rise residential building features in the [alternate -combined example project feature file](https://github.com/urbanopt/urbanopt-cli/blob/e7d29764eb9ae837078f92a488adb783a3e52616/example_files/example_project_combined.json). It is to be noted, that these values are meant to be representative -to illustrate how templates can be used to customize -the workflow for different communities and are not based on an actual community or formal study. Users should ensure that specific assumptions in their templates are accurate for the homes/communities they are modeling. diff --git a/workflows/residential_workflows/multifamily.md b/workflows/residential_workflows/multifamily.md deleted file mode 100644 index bdd3c6c9..00000000 --- a/workflows/residential_workflows/multifamily.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -layout: default -title: Low-Rise Multifamily -parent: Residential Workflows -grand_parent: Workflows -nav_order: 3 ---- - -## Low-Rise Multifamily - -Consider the highlighted "Low-Rise Multifamily" building footprint with the following high-level URBANopt™ GeoJSON inputs: - -* 2 stories above ground -* slab foundation -* flat roof -* 8 living units -* double exterior corridor - -![multifamily](../../doc_files/multifamily-footprint.jpg) - -The number of living units and stories above ground are used to determine the position (i.e., horizontal location and vertical level) of individual living units contained in the building. -By determining the position of individual units relative the whole building, types and boundary conditions of surfaces (e.g., adiabatic) can be stored in the HPXML. - -Example 3D renderings for a single unit from the building is shown below. -This unit is designated as having a "Left" horizontal location and a "Top" vertical level (when viewing from the front). -You can see outside boundary conditions of "Outdoors" on the roof and one facade, and "Adiabatic" on the floor and opposite facade. - -![multifamily](../../doc_files/multifamily-1-1.jpg) -![multifamily](../../doc_files/multifamily-1-2.jpg) -![multifamily](../../doc_files/multifamily-1-3.jpg) -![multifamily](../../doc_files/multifamily-1-4.jpg) - -Note that the footprint of the modeled unit is always rectangular even though the GeoJSON footprint may not be. See [Other Assumptions](residential_workflows#other-assumptions) for more information. - -For each unit of the building, an HPXML and OSM model is constructed. -These OSM models are merged into a single OSM model, as shown below. - -![multifamily](../../doc_files/multifamily-2.jpg) - - -### Modeling Notes - -- "Low-Rise Multifamily" home models may be heated only, cooled only, or both heated and cooled. - - Partial Conditioning: heating and cooling may be applied to just a portion of the living space of the home or to the entire living space. Representation of partial conditioning of the living space of a home is accomplished by adding ideal air load system to heat and cool the unconditioned portion of the living area. In this situation, district heating or cooling loads may show up in end uses for the home. - - Undersized Mechanical System: District heating or cooling loads may also show up in end uses when a designed mechanical system cannot meet the load required to maintain thermostat temperatures. An example would be an evaporative cooling system in a hot humid climate. - - For both the partially conditioned and undersized examples, it is possible for reporting or post processing to filter out these unintended district heating and cooling loads. -- It is important to know, that unlike the commercial models that will result in unmet heating or cooling hours, the residential models will not have any unmet heating or cooling hours. To understand how the HVAC system is conditioning for "Low-Rise Multifamily" home models, users should look at district heating and cooling loads. - - -### GeoJSON Schema - -The [URBANopt GeoJSON schema](https://github.com/urbanopt/urbanopt-geojson-gem/blob/develop/lib/urbanopt/geojson/schema/building_properties.json) differentiates between sets of required and optional fields for "Low-Rise Multifamily" residential buildings: - -Required fields: - -| Field | Type | Enums | Notes | -| ----------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| floor_area | number | | Total conditioned floor area. | -| footprint_area | number | | First floor conditioned floor area. | -| number_of_stories_above_ground| integer | | | -| number_of_stories | integer | | Includes foundations. | -| number_of_residential_units | integer | | Divisible by stories. | -| number_of_bedrooms | integer | | Must be > 0. | -| foundation_type | string | (1) slab
(2) crawlspace - vented
(3) crawlspace - unvented
(4) basement - unconditioned
(5) ambient | Invalid:
(1) crawlspace - conditioned
(2) basement - conditioned | -| attic_type | string | (1) attic - vented
(2) attic - unvented
(3) flat roof | Invalid:
(1) attic - conditioned | - -Optional fields: - -| Field | Type | Enums | Notes | -| ----------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| roof_type | string | (1) Gable
(2) Hip | NA when attic type is flat roof. | -| occupancy_calculation_type | string | (1) asset
(2) operational | | -| number_of_occupants | integer | | For operational calculations. | -| system_type | string | (1) electric resistance
(2) furnace
(3) boiler
(4) central air conditioner
(5) room air conditioner
(6) evaporative cooler
(7) air-to-air heat pump
(8) mini-split heat pump
(9) ground-to-air-heat-pump | | -| system_type | string | (1) electric resistance
(2) furnace
(3) boiler
(4) central air conditioner
(5) room air conditioner
(6) evaporative cooler
(7) air-to-air heat pump
(8) mini-split heat pump
(9) ground-to-air-heat-pump | | -| heating_system_fuel_type | string | (1) electricity
(2) natural gas
(3) fuel oil
(4) propane
(5) wood | | -| template | string | | See [Customizable Template](residential_workflows#customizable-template) | -| hpxml_directory | string | | Relative to xml_building. Most required fields are then optional. | - -An example "Low-Rise Multifamily" building feature snippet is shown below. - - ```json - { - "type": "Feature", - "properties": { - "id": "18", - "name": "Residential 5", - "type": "Building", - "building_type": "Multifamily", - "floor_area": 28636, - "footprint_area": 14318, - "number_of_stories_above_ground": 2, - "number_of_stories": 2, - "number_of_bedrooms": 16, - "foundation_type": "slab", - "attic_type": "flat roof", - "system_type": "Residential - furnace and room air conditioner", - "heating_system_fuel_type": "wood", - "number_of_residential_units": 8, - "template": "Residential IECC 2015 - Customizable Template Sep 2020" - } - ``` diff --git a/workflows/residential_workflows/single_family_detached.md b/workflows/residential_workflows/other_details.md similarity index 59% rename from workflows/residential_workflows/single_family_detached.md rename to workflows/residential_workflows/other_details.md index a24f148d..0cf7e803 100644 --- a/workflows/residential_workflows/single_family_detached.md +++ b/workflows/residential_workflows/other_details.md @@ -1,61 +1,48 @@ --- layout: default -title: Single-Family Detached +title: Other Details parent: Residential Workflows grand_parent: Workflows -nav_order: 1 +nav_order: 4 --- -## Single-Family Detached +## Other Details -Consider the highlighted "Single-Family Detached" building footprint with the following high-level URBANopt™ GeoJSON inputs: - -* 1 story above ground -* unvented crawlspace foundation -* vented attic -* 2 car garage - -![single_family_detached](../../doc_files/single-family-detached-footprint.jpg) - -An example 3D rendering of the single-family detached building is shown below. - -![single_family_detached](../../doc_files/single-family-detached-1.jpg) - -Note that the footprint of the modeled unit, less the garage, is always rectangular even though the GeoJSON footprint may not be. See [Other Assumptions](residential_workflows#other-assumptions) for more information. - -The 3D building surfaces stored in HPXML and OSM models represent the area and orientation of ground and exterior exposure of surfaces, but do not represent their position relative to each other. -An example geometry rendering for a translated HPXML file is given below. - -![single_family_detached](../../doc_files/single-family-detached-2.jpg) +Other modeling details are described for the following categories: +- [Modeling Notes](#modeling-notes) +- [GeoJSON Schema](#geojson-schema) +- [Assumptions](#assumptions) ### Modeling Notes -- "Single-Family Detached" home models may contain unconditioned non-living spaces that are included as part of the total building area, such as a garage. As a result energy use intensities (EUIs) for homes, often calculated in units of kBtu/sqft/yr, will vary based on the unconditioned floor area if total building area is used for the calculation. Alternatively, conditioned floor area can be used for such calculations. -- "Single-Family Detached" home models may be heated only, cooled only, or both heated and cooled. +- The building footprint drawn and contained in the GeoJSON does not determine the footprint of individual modeled units. +- Floor area is divided by the number of residential units to determine the floor area of each individual unit. +- Individual footprints are determined using this unit floor area and an aspect ratio of 2 (i.e., front/back walls are twice as long as left/right walls). +- Single-Family Detached home models may contain unconditioned non-living spaces that are included as part of the total building area, such as a garage. As a result energy use intensities (EUIs) for homes, often calculated in units of kBtu/sqft/yr, will vary based on the unconditioned floor area if total building area is used for the calculation. Alternatively, conditioned floor area can be used for such calculations. +- Home models for all building types may be heated only, cooled only, or both heated and cooled. - Partial Conditioning: heating and cooling may be applied to just a portion of the living space of the home or to the entire living space. Representation of partial conditioning of the living space of a home is accomplished by adding ideal air load system to heat and cool the unconditioned portion of the living area. In this situation, district heating or cooling loads may show up in end uses for the home. - Undersized Mechanical System: District heating or cooling loads may also show up in end uses when a designed mechanical system cannot meet the load required to maintain thermostat temperatures. An example would be an evaporative cooling system in a hot humid climate. - For both the partially conditioned and undersized examples, it is possible for reporting or post processing to filter out these unintended district heating and cooling loads. -- It is important to know, that unlike the commercial models that will result in unmet heating or cooling hours, the residential models will not have any unmet heating or cooling hours. To understand how the HVAC system is conditioning for "Single-Family Detached" home models, users should look at district heating and cooling loads. - +- It is important to know, that unlike the commercial models that will result in unmet heating or cooling hours, the residential models will not have any unmet heating or cooling hours. To understand how the HVAC system is conditioning for home models, users should look at district heating and cooling loads. ### GeoJSON Schema -The [URBANopt GeoJSON schema](https://github.com/urbanopt/urbanopt-geojson-gem/blob/develop/lib/urbanopt/geojson/schema/building_properties.json) differentiates between sets of required and optional fields for "Single-Family Detached" residential buildings: +The [URBANopt GeoJSON schema](https://github.com/urbanopt/urbanopt-geojson-gem/blob/develop/lib/urbanopt/geojson/schema/building_properties.json) differentiates between sets of **required** and **optional** fields for Single-Family Detached, Single-Family Attached, and Low-Rise Multifamily residential buildings. -Required fields: +**Required** fields: -| Field | Type | Enums | Notes | +| Field | Data Type | Enums | Notes | | ----------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | floor_area | number | | Total conditioned floor area. | | footprint_area | number | | First floor conditioned floor area. | | number_of_stories_above_ground| integer | | | | number_of_stories | integer | | Includes foundations. | | number_of_bedrooms | integer | | Must be > 0. | -| foundation_type | string | (1) slab
(2) crawlspace - vented
(3) crawlspace - unvented
(4) crawlspace - conditioned
(5) basement - unconditioned
(6) basement - conditioned
(7) ambient | | -| attic_type | string | (1) attic - vented
(2) attic - unvented
(3) attic - conditioned
(4) flat roof | Stories > 1 for conditioned attics. | +| foundation_type | string | (1) slab
(2) crawlspace - vented
(3) crawlspace - unvented
(4) crawlspace - conditioned
(5) basement - unconditioned
(6) basement - conditioned
(7) ambient | Excluding (4) and (6) for Low-Rise Multifamily. | +| attic_type | string | (1) attic - vented
(2) attic - unvented
(3) attic - conditioned
(4) flat roof | Excluding (3) for Low-Rise Multifamily. Stories > 1 for (3). | -Optional fields: +**Optional** fields: | Field | Type | Enums | Notes | | ----------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | @@ -64,30 +51,47 @@ Optional fields: | number_of_occupants | integer | | For operational calculations. | | system_type | string | (1) electric resistance
(2) furnace
(3) boiler
(4) central air conditioner
(5) room air conditioner
(6) evaporative cooler
(7) air-to-air heat pump
(8) mini-split heat pump
(9) ground-to-air-heat-pump | | | heating_system_fuel_type | string | (1) electricity
(2) natural gas
(3) fuel oil
(4) propane
(5) wood | | -| onsite_parking_fraction | number | (1) No (0)
(2) Yes (1) | | -| template | string | | See [Customizable Template](residential_workflows#customizable-template) | -| hpxml_directory | string | | Relative to xml_building. Most required fields are then optional. | - -An example "Single-Family Detached" building feature snippet is shown below. - - ```json - { - "type": "Feature", - "properties": { - "id": "14", - "name": "Residential 1", - "type": "Building", - "building_type": "Single-Family Detached", - "floor_area": 3055, - "footprint_area": 3055, - "number_of_stories_above_ground": 1, - "number_of_stories": 1, - "number_of_bedrooms": 3, - "foundation_type": "crawlspace - unvented", - "attic_type": "attic - vented", - "system_type": "Residential - furnace and central air conditioner", - "heating_system_fuel_type": "natural gas", - "onsite_parking_fraction": 1, - "template": "Residential IECC 2015 - Customizable Template Sep 2020" - } - ``` +| onsite_parking_fraction | number | (1) No (0)
(2) Yes (1) | For Single-Family Detached only. | +| hpxml_directory | string | | Relative to the ``xml_building`` folder. Required fields become optional. | +| template | string | | See [Customizable Template](building_inputs.md#customizable-template) | +| characterize_residential_buildings_from_buildstock_csv | string | | See [ResStock Samples](building_inputs.md#resstock-samples) | +| resstock_buildstock_csv_path | string | | See [ResStock Samples](building_inputs.md#resstock-samples) | +| uo_buildstock_mapping_csv_path | string | | See [ResStock Samples](building_inputs.md#resstock-samples) | + +### Assumptions + +A summary of modeling assumptions baked into the baseline mapper is given below. +In the future, updates/improvements could be made to expose these arguments as inputs to the models. +For example, aspect ratio could be either user-defined or determined from the drawn building footprint. +Another example is allowing building orientation to be user-defined, or determining it based on the "front" of the building. + +#### Geometry: Aspect Ratio +The aspect ratio of individual units of the building is assumed to be 2. + +#### Geometry: Foundations +For buildings with a crawlspace foundation, the height of the foundation is assumed to be 3 ft. +For buildings with a basement or ambient foundation, the height of the foundation is assumed to be 8 ft. + +#### Geometry: Walls +The average height of walls adjacent to living space is 8 ft. + +#### Geometry: Neighbors +It is assumed that buildings have no neighbors. + +#### Geometry: Orientation +For Single-Family Detached and Single-Family Attached buildings, 100% of the building units are oriented to the South. +For Low-Rise Multifamily buildings, 50% of the building units are oriented to the South while the other 50% are oriented to the North. + +#### Geometry: Garages +For Single-Family Detached buildings with garages, the size of the garage depends on the floor area. +The garage is assumed to be a 1-car (12 ft wide) for buildings 2500 ft2 or less, and 2-car (24 ft wide) for buildings greater than 2500 ft2. +The garage is also assumed to protrude from the building 100% (i.e., no portion of it is tucked within the building). + +#### Geometry: Corridor +For Low-Rise Multifamily buildings, the corridor is assumed to be a "Double Exterior" corridor (i.e., entrances to individual units are from the exterior of the building). + +#### Fuel Types: Appliances +The fuel type of the cooking range, oven, and clothes dryer is assumed to match the fuel type of the heating system. + +#### Fuel Types: Water Heating +The fuel type of the water heater is assumed to match the fuel type of the heating system. \ No newline at end of file diff --git a/workflows/residential_workflows/residential_workflows.md b/workflows/residential_workflows/residential_workflows.md index 212780bc..b7f8088d 100644 --- a/workflows/residential_workflows/residential_workflows.md +++ b/workflows/residential_workflows/residential_workflows.md @@ -9,151 +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 each living unit of the building, or -1. a set of pre-built HPXML files is used to represent each of the living units of the building. +1. an [HPXML](https://hpxml.nrel.gov) file is built to represent living unit(s) of the building, or +1. a pre-built HPXML file is used to represent living unit(s) of the building. -For example, in the case of a single-family detached building one HPXML file is built to represent the single unit. -HPXML files are built based on feature information contained in the GeoJSON file as well as on sets of default assumptions contained in the following [lookup files](https://github.com/urbanopt/urbanopt-example-geojson-project/tree/develop/example_project/mappers/residential): +For example, in the case of a single-family detached building one HPXML file is built to represent the single dwelling unit. +In the case of a multifamily building one HPXML file is built containing multiple dwelling units. -* clothes_dryer.tsv -* clothes_washer.tsv -* cooling_system.tsv -* dishwasher.tsv -* enclosure.tsv -* heat_pump.tsv -* heating_system.tsv -* mechanical_ventilation.tsv -* exhaust.tsv -* refrigerator.tsv -* water_heater.tsv +The following sections describe the types of buildings supported by this workflow and how input values are assigned to various arguments. -Argument values found in these lookup files span across the following categories: - -* enclosure (insulation levels, air leakage, etc.) -* HVAC systems (heating/cooling types, efficiencies, etc.) -* appliances (refrigerator, clothes washer, etc.) -* ventilation (mechanical, exhaust) -* water heater - -See the [Customizable Template](#customizable-template) section below for more information on controlling how these assumptions are made. - -A translator measure is then applied to each HPXML file to construct an OpenStudio© building model. - -## Supported Building Types - -Currently, the following residential building types are supported: - -- [**Single-Family Detached**](./single_family_detached) -- [**Single-Family Attached**](./single_family_attached) -- [**Low-Rise Multifamily**](./multifamily)[^1] - -Only the *Baseline* and *High Efficiency* Scenarios are supported at this time; any additional mappers will need to be updated manually. - -Note that the modeling capabilities for these building types are currently in Beta mode. -This means that testing and development is still in progress, and user feedback is welcome. - -[^1]: Mid-Rise and High-Rise Multifamily building prototypes can be found in the commercial building workflows). - -## Customizable Template - -An optional template enumeration may be specified for each feature in the GeoJSON. -Enumerations that are applicable to residential buildings: - -- `Residential IECC 2006 - Customizable Template Sep 2020` -- `Residential IECC 2009 - Customizable Template Sep 2020` -- `Residential IECC 2012 - Customizable Template Sep 2020` -- `Residential IECC 2015 - Customizable Template Sep 2020` -- `Residential IECC 2018 - Customizable Template Sep 2020` -- `Residential IECC 2006 - Customizable Template Apr 2022` -- `Residential IECC 2009 - Customizable Template Apr 2022` -- `Residential IECC 2012 - Customizable Template Apr 2022` -- `Residential IECC 2015 - Customizable Template Apr 2022` -- `Residential IECC 2018 - Customizable Template Apr 2022` - -If no template enumeration is specified, argument values will be defaulted according to the [documentation](https://openstudio-hpxml.readthedocs.io/en/latest/workflow_inputs.html) for the OpenStudio-HPXML workflow. -In general, these defaults are based on **ANSI / RESNET / ICC Std. 301 (2006)**. - -All argument values for the previous categories may be customized by manually adjusting values in -the lookup files, or a new customizable template with unique argument values may be created as -described under [customization](customization.md). -The enumeration names include "Residential IECC 20XX" because a variety of enclosure, window, duct insulation, and whole-home air leakage assumptions are based on the different IECC model code years to illustrate how templates can be used to approximate different levels of efficiency. -Note that not all possible assumptions have been aligned with IECC requirements (e.g., see above regarding defaults), but the users can further customize these templates as needed for specific projects. - -## Occupancy - -The user has control over both occupant-related schedule types and the occupancy calculation type. - -### Schedules - -Occupant-related schedules can be either defaulted or stochastically generated, and may vary either building-to-building or unit-to-unit. -The default behavior is to use stochastically generated schedules that vary unit-to-unit, but the user has control to both use defaulted schedules and vary them building-to-building. -Note that there are runtime impacts associated with using stochastically generated schedules and for varying schedules unit-to-unit. - -Stochastic schedules are generated using time-inhomogenous Markov chains derived from American Time Use Survey data, supplemented with sampling duration and power level from NEEA RBSA data, as well as DHW draw duration and flow rate data from Aquacraft/AWWA data. - -In terms of repeatability, stochastic schedules generation uses a pseudo-random number generator that takes a seed as an argument. -The seed is determined by the index of a given feature relative to all features in the GeoJSON, and then multiplied by the unit number within the building. -For schedules that vary by building, the schedules that correspond to the first unit are used for all units of the building. -Relocating a feature's position within a GeoJSON would change the seed argument for that building. - -### Calculation Type - -Occupancy-based loads (i.e., plug loads, appliances, hot water, etc.) can be calculated through either: - -1. an asset calculation, or -1. an operational calculation. - -The default behavior is to perform an asset calculation, but the user has control to enable an operational calculation. - -Asset calculations are performed using number of bedrooms and/or conditioned floor area. - -Operational calculations are performed using an adjustment for the number of occupants. - -## Other Assumptions - -The building footprint drawn and contained in the GeoJSON does not determine the footprint of individual modeled units. -Floor area is divided by the number of residential units to determine the floor area of each individual unit. -Individual footprints are determined using this unit floor area and an aspect ratio of 2 (i.e., front/back walls are twice as long as left/right walls). - -A summary of modeling assumptions baked into the baseline mapper is given below. -In the future, updates/improvements could be made to expose these arguments as inputs to the models. -For example, aspect ratio could be either user-defined or determined from the drawn building footprint. -Another example is allowing building orientation to be user-defined, or determining it based on the "front" of the building. - -### Geometry - -#### Aspect Ratio -The aspect ratio of individual units of the building is assumed to be 2. - -#### Foundations -For buildings with a crawlspace foundation, the height of the foundation is assumed to be 3 ft. -For buildings with a basement or ambient foundation, the height of the foundation is assumed to be 8 ft. - -#### Walls -The average height of walls adjacent to living space is 8 ft. - -#### Neighbors -It is assumed that buildings have no neighbors. - -#### Orientation -For Single-Family Detached and Single-Family Attached buildings, 100% of the building units are oriented to the South. -For Low-Rise Multifamily buildings, 50% of the building units are oriented to the South while the other 50% are oriented to the North. - -#### Garages -For Single-Family Detached buildings with garages, the size of the garage depends on the floor area. -The garage is assumed to be a 1-car (12 ft wide) for buildings 2500 ft2 or less, and 2-car (24 ft wide) for buildings greater than 2500 ft2. -The garage is also assumed to protrude from the building 100% (i.e., no portion of it is tucked within the building). - -#### Corridor -For Low-Rise Multifamily buildings, the corridor is assumed to be a "Double Exterior" corridor (i.e., entrances to individual units are from the exterior of the building). - -### Fuel Types - -#### Appliances -The fuel type of the cooking range, oven, and clothes dryer is assumed to match the fuel type of the heating system. - -#### Water Heating -The fuel type of the water heater is assumed to match the fuel type of the heating system. +- [Building Types](building_types.md) lists the supported residential building types, including feature properties, example 3D renderings, and feature snippets. +- [Building Inputs](building_inputs.md) describes various paths for assigning building model input values for GeoJSON features. +- [Building Occupancy](building_occupancy.md) includes information about schedule and calculation types. +- [Other Details](other_details.md) describes modeling notes, GeoJSON schema details, and assumptions related to geometry and fuel types. diff --git a/workflows/residential_workflows/single_family_attached.md b/workflows/residential_workflows/single_family_attached.md deleted file mode 100644 index a710c0b3..00000000 --- a/workflows/residential_workflows/single_family_attached.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -layout: default -title: Single-Family Attached -parent: Residential Workflows -grand_parent: Workflows -nav_order: 2 ---- - -## Single-Family Attached - -Consider the highlighted "Single-Family Attached" building footprint with the following high-level URBANopt™ GeoJSON inputs: - -* 2 stories above ground -* slab foundation -* vented attic -* 4 living units -* no rear units - -![single_family_attached](../../doc_files/single-family-attached-footprint.jpg) - -The number of living units are used to determine the position (i.e., horizontal location) of individual living units contained in the building. -By determining the position of individual units relative the whole building, types and boundary conditions of surfaces (e.g., adiabatic) can be stored in the HPXML. - -Example 3D renderings for a single unit from the building is shown below. -This unit is designated as having a "Right" horizontal location (when viewing from the front). -You can see outside boundary conditions of "Outdoors" on one facade, and "Adiabatic" on the opposite facade. - -![single_family_attached](../../doc_files/single-family-attached-1-1.jpg) -![single_family_attached](../../doc_files/single-family-attached-1-2.jpg) - -Note that the footprint of the modeled unit is always rectangular even though the GeoJSON footprint may not be. See [Other Assumptions](residential_workflows#other-assumptions) for more information. - -For each unit of the building, an HPXML and OSM model is constructed. -These OSM models are merged into a single OSM model, as shown below. - -![single_family_attached](../../doc_files/single-family-attached-2.jpg) - - -### Modeling Notes - -- "Single-Family Attached" home models may be heated only, cooled only, or both heated and cooled. - - Partial Conditioning: heating and cooling may be applied to just a portion of the living space of the home or to the entire living space. Representation of partial conditioning of the living space of a home is accomplished by adding ideal air load system to heat and cool the unconditioned portion of the living area. In this situation, district heating or cooling loads may show up in end uses for the home. - - Undersized Mechanical System: District heating or cooling loads may also show up in end uses when a designed mechanical system cannot meet the load required to maintain thermostat temperatures. An example would be an evaporative cooling system in a hot humid climate. - - For both the partially conditioned and undersized examples, it is possible for reporting or post processing to filter out these unintended district heating and cooling loads. -- It is important to know, that unlike the commercial models that will result in unmet heating or cooling hours, the residential models will not have any unmet heating or cooling hours. To understand how the HVAC system is conditioning for "Single-Family Attached" home models, users should look at district heating and cooling loads. - - -### GeoJSON Schema - -The [URBANopt GeoJSON schema](https://github.com/urbanopt/urbanopt-geojson-gem/blob/develop/lib/urbanopt/geojson/schema/building_properties.json) differentiates between sets of required and optional fields for "Single-Family Attached" residential buildings: - -Required fields: - -| Field | Type | Enums | Notes | -| ----------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| floor_area | number | | Total conditioned floor area. | -| footprint_area | number | | First floor conditioned floor area. | -| number_of_stories_above_ground| integer | | | -| number_of_stories | integer | | Includes foundations. | -| number_of_residential_units | integer | | | -| number_of_bedrooms | integer | | Must be > 0. | -| foundation_type | string | (1) slab
(2) crawlspace - vented
(3) crawlspace - unvented
(4) crawlspace - conditioned
(5) basement - unconditioned
(6) basement - conditioned
(7) ambient | | -| attic_type | string | (1) attic - vented
(2) attic - unvented
(3) attic - conditioned
(4) flat roof | Stories > 1 for conditioned attics. | - -Optional fields: - -| Field | Type | Enums | Notes | -| ----------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| roof_type | string | (1) Gable
(2) Hip | NA when attic type is flat roof. | -| occupancy_calculation_type | string | (1) asset
(2) operational | | -| number_of_occupants | integer | | For operational calculations. | -| system_type | string | (1) electric resistance
(2) furnace
(3) boiler
(4) central air conditioner
(5) room air conditioner
(6) evaporative cooler
(7) air-to-air heat pump
(8) mini-split heat pump
(9) ground-to-air-heat-pump | | -| heating_system_fuel_type | string | (1) electricity
(2) natural gas
(3) fuel oil
(4) propane
(5) wood | | -| template | string | | See [Customizable Template](residential_workflows#customizable-template) | -| hpxml_directory | string | | Relative to xml_building. Most required fields are then optional. | - -An example "Single-Family Attached" building feature snippet is shown below. - - ```json - { - "id": "17", - "name": "Residential 4", - "type": "Building", - "building_type": "Single-Family Attached", - "floor_area": 18320, - "footprint_area": 9160, - "number_of_stories_above_ground": 2, - "number_of_stories": 2, - "number_of_bedrooms": 6, - "foundation_type": "slab", - "attic_type": "attic - vented", - "system_type": "Residential - furnace and room air conditioner", - "heating_system_fuel_type": "fuel oil", - "number_of_residential_units": 4, - "template": "Residential IECC 2015 - Customizable Template Sep 2020" - } - ```