Residential: connect to ResStock

[joseph-robertson]

This PR makes several changes/updates. They are summarized into the following items:

• (A) Replace hpxml-measures with residential-measures
• (B) Refactor Baseline.rb's residential paths
• (C) Write new residential_samples path
• (D) Write new BuildResidentialModel unit tests

Details are given below.

(A) Replace example_project/resources/hpxml-measures with example_project/resources/residential-measures. The latter has hpxml-measures in it. A new update_residential rake task is created for git cloning (as opposed to git subtree) the resstock repository with a depth of 1 and renaming it to residential-measures. The rake task also removes a bunch of files and folders that UO doesn't need.

(B) The set of residential paths are now:

• Argument values assigned using OpenStudio-HPXML defaults, or
• Defaults + Argument values assigned using residential_template (customizable lookup files), or
• Defaults + Argument values assigned using residential_samples (ResStock parameter/options)

(C) To the Baseline.rb mapper, add optional residential_samples method (similar to the optional residential_template method).

The residential_samples path connects to a user-specified ResStock buildstock CSV file:

• if resstock_buildstock_csv_path is populated in the GeoJSON file, finds/sets a resstock_building_id for URBANopt's BuildResidentialModel measure
• if uo_buildstock_mapping_csv_path is populated in the GeoJSON file, uses the resstock_building_id mapped by feature ID for URBANopt's BuildResidentialModel measure

Both resstock_buildstock_csv_path and uo_buildstock_mapping_csv_path CSV files may be a subset of all ResStock parameters. Any arguments not assigned because of missing parameters will be filled in with defaults.

Copy some code from ResStock's BuildExistingModel measure into BuildResidentialModel measure. (It probably doesn't make sense to call ResStock's BuildExistingModel directly because it currently creates HPXML files with only a single dwelling unit. Even if it could create multiple dwelling units, they'd all be identical?)

(D) Add new test_residential_samplesXXX tests to the test_build_residential_model.rb test file that checks combinations of buildstock CSV file paths and resstock building IDs.

---

Checklist / Questions:

• make a better distinction between the "Feature ID" and the "ResStock Building ID" (building_id -> resstock_building_id)
• resstock subtree considerations
  • think about whether we need to remove some resstock repo files (it's pretty huge)
    • ideally, yes, we wouldn't want any resstock files that we don't actually need
  • is it confusing to replace hpxml-measures with resstock/resources/hpxml-measures? seems redundant to store both.
    • it's confusing to have folder name "resstock" within UO; perhaps we could change the folder name to something like "residential" or "residential-measures"?
  • really we only want "hpxml-measures", "options_lookup.tsv", "ResStockArguments", and maybe a few other resource files
• address all FIXMEs and TODOs
• design/implement the geojson schema changes Added UO-ResStock connection variable to the site properties schema urbanopt-geojson-gem#270
• add a new sample feature to example_project_combined.json that demonstrates the new residential_samples path?
• should each dwelling unit of a building be identical when using the ResStock path? or should some options in the lookup be ignored (i.e., foundation/attic type, unit vertical/horizontal location relative the building)?
  • Example 1: for a MF building, we determine foundation/attic type and orientation for each dwelling unit.
  • Example 2: weather station epw is assigned in the mapper.
  • initial thought is that we should follow UO's logic for determining unit positions; this gives variability that we otherwise wouldn't have
  • follow-up thought here is that we shouldn't; e.g., duct location can conflict with "new" foundation type
• think about how to throw a warning in case the user-provided buildstock CSV file does not sync with the checkout of resstock? maybe it's enough to just call test/check_buildstock.rb here?
• why doesn't feature.osw get written to the test run folder?

[joseph-robertson]

Questions after running Feature ID = 18, which returns Building ID = 1654.

They have different:

• foundation/attic types
• HVAC system types
• heating fuel types

Should we be matching on these parameters/properties, or does this constrain the search too much?

Currently if no match is found, we error out. Is there a better / more flexible approach here? Should we iteratively remove a parameter, re-do the search, etc etc?

[joseph-robertson]

Questions after running Feature ID = 18, which returns Building ID = 1654.

They have different:

• foundation/attic types
• HVAC system types
• heating fuel types

Should we be matching on these parameters/properties, or does this constrain the search too much?

Currently if no match is found, we error out. Is there a better / more flexible approach here? Should we iteratively remove a parameter, re-do the search, etc etc?

Seems like we may want to update the GeoJSON schema such that when resstock_buildstock_csv_path or uo_buildstock_mapping_csv_path is present, other required fields like foundation_type and attic_type are not required. And then we map foundation/attic type to resstock options when present. Otherwise you can run into trouble:

• you'll either override the feature-specified foundation/attic type (and corresponding insulation) based on the selected resstock sample, or
• you'll ignore the foundation/attic type override but also need to ignore corresponding sampled insulation

[joseph-robertson]

Some meeting notes:

• general approach will be to respect what's in either buildstock csv, with the exception of geometry_unit_cfa
• resstock_buildstock_csv_path
  • should come with a warning that random could lead to issues
  • more properties in geojson specified, less samples matched
  • also depends on size of buildstock.csv
• uo_buildstock_mapping_csv_path
  • should emphasize that this is an improvement or more innovative where the user has the ability to specify the appropriate set of characteristics
  • the responsibility is on the user to ensure they do not supply contradictory parameter/options

[joseph-robertson]

Meeting notes:

• we should have instructions regarding (a) how to get a buildstock.csv, and (b) other details (where to put it, etc etc)
• need to double-check whether "random" is seeded or not, so we don't get different results in a re-run
  • yes, it's seeded: selected_ids = matches.sample(1, random: Random.new(12345))
• what is the buildstock.csv "schema"? point to resstock RTD? to options_lookup? to example buildstock.csv?
• find out how to run the residential unit tests locally (so we can implement in CI). just pass the test file to OS CLI:
  • C:\openstudio-3.7.0\bin\openstudio.exe .\example_project\measures\BuildResidentialModel\tests\test_build_residential_model.rb -n test_residential_samples
  • bundle exec rake residential:measure_tests <--- per Nate, this already runs on CI
• should we highlight that this is a "beta" version? probably yes
  • in a changelog?
  • in the documentation?
• update compatibility matrix in docs to be 0.13.0 and not 1.0.0

[vtnate]

@joseph-robertson Does this PR resolve #192?

Issue is not valid