nrel / resstock

Highly granular modeling of residential building stocks at national, regional, and local scales using OpenStudio/EnergyPlus.

The develop branch is under active development. Find the latest release here.

ResStock™, built on the OpenStudio platform, is a project geared at modeling existing residential building stocks at national, regional, or local scales with a high-degree of granularity (e.g., one physics-based simulation model for every 200 dwelling units), using the EnergyPlus simulation engine. Information about ComStock™, a sister tool for modeling the commercial building stock, can be found here.

This repository contains:

• Housing characteristics of the U.S. residential building stock, in the form of conditional probability distributions stored as tab-separated value (.tsv) files. Comments at the bottom of each file document data sources and assumptions for each.
• A library of housing characteristic "options" that translate high-level characteristic parameters into arguments for OpenStudio measures, and which are referenced by the housing characteristic .tsv files and building energy upgrades defined in project definition files
• Project definition buildstockbatch YML files openable in any text editor for v2.3.0 and later
• Unit-level OpenStudio-HPXML Measures (v3.0.0 and later) for automatically constructing individual representative dwelling unit OpenStudio Models using OpenStudio-HPXML
• Higher-level OpenStudio Measures for controlling simulation inputs and outputs

Software for running ResStock simulations:

• Versions 2.3.0 and later only support the use of buildstockbatch for deploying simulations on high-performance or cloud computing. Version 2.3.0 also removed separate projects for single-family detached and multifamily buildings, in lieu of a combined project_national representing the U.S. residential building stock. See the changelog for more details.
• For large-scale production runs of ResStock, it is recommended that buildstockbatch is used. For smaller-scale tests, run_analysis.rb can be used. Information about the workflow can be found in ResStock's documentation.

resstock's Issues

Location census division tsv

From RECS data.

Options:

• 'New England', 'East North Central', 'Middle Atlantic', 'Mountain - Pacific', 'South Atlantic - East South Central', 'West North Central', 'West South Central'

Dependencies:

• Location EPW

To connect EPW with RECS data, create a lookup file: usaf-->state-->division

@ejhw

update clothes dryer mapping

Propane into natural gas bin.

Option -> multiple measures

Add support for mapping one option to multiple measures. Some examples where this is needed:

• Geometry: Need to call Simple Geometry measure and Num Beds/Baths measure
• Location EPW: Need to call OpenStudio measure and EnergyPlus measure

Likely implementation will be allowing additional rows in options_lookup.txt for a given option.

Update probability distributions

Need to update some parameters (due to bin changes for house size and # stories):

• Geometry House Size.tsv
• Geometry Stories.tsv - National
• Geometry Garage.tsv - National & PNW (use National for both)
• Geometry.tsv
• Infiltration.tsv - National

We can't do any new runs until these are updated.

Airflow Handling

Since we have a single EnergyPlus measure that handles everything related to airflow, we'll need to use a similar approach as was done for geometry. In other words, we'll have multiple probability distribution files (one for each parameter, e.g., air leakage, natural ventilation, ducts, ...) plus one for airflow. The airflow file will depend on the other parameters, with all combinations as columns, and values of either 0 or 1.

• Ducts (interaction w/HVAC equipment)
• Air Leakage
• Natural Ventilation
• Mechanical Ventilation
• Vented vs Unvented Crawl
• Vented vs Unvented Unfinished Attic
• Clothes Dryer venting
• runner.lastOpenStudioModel.get error

Remove R-value area weighting?

Currently, we are (surface) area-weighting R-values for: wall insulation, attic insulation, slab insulation, etc.

Income tsv

Options:

• '0-25K', '25-50K', '50-75K', '75-100K', '100-125K', '125-150K', '150-200K', '200K+'

@ejhw

Incorporate house size scaling into ResStock CSV output results

Use lookup table queried from RBSA by vintage and size bin.

HVAC system cooling type tsv

From AHS data, not RECS.

Options:

• 'Central', 'Room', 'None'

Dependences:

• HVAC System Cooling
  • 'None', 'AC, SEER 8', 'AC, SEER 10', 'AC, SEER 13', 'AC, SEER 15', 'Room AC, EER 8.5, 20% Conditioned', 'Room AC, EER 10.7, 20% Conditioned'

@ejhw

Reporting of other fuels

When there is other fuel consumption reported by OS/E+, determine if a given end use is oil or propane by looking at the building model/characteristics and disaggregate accordingly in our reporting measure. Clever idea provided by @jmaguire1.

Geometry handling

Per discussion with @ewilson, we'll have multiple probability distribution files (one for each parameter, e.g., stories, size, ...) plus one for geometry. The geometry file will depend on the other parameters, with all combinations as columns, and values of either 0 or 1.

Implemented in a13e7ab

Some caveats remain:

1. This is a simplified rectangular geometry (including garage), not like our detailed BEopt implementation.
2. I've hard-coded the aspect ratio as 1.0 for now.
3. The simple geometry measure can result in small distances between the garage back wall and the living space back wall.
   4. I need to look into NumStories relationship to presence of Finished Basement.

Can't specify some upgrades

Upgrades that refer to the AirflowOriginalModel measure won't run because it's an EnergyPlus measure. To accommodate it now, we'd have to create an EnergyPlus measure version of the ApplyUpgrade measure, which is a real pain. Instead, we'll wait on https://github.com/NREL/OpenStudio-BEopt/issues/40 and switch to the Airflow measure when we can.

This affects: ducts, infiltration, mechanical ventilation, attic insulation, crawlspace insulation, water heaters, HVAC heating systems, and clothes dryers.

The example attic insulation upgrade in the analysis spreadsheets has been temporarily switched to a wall insulation upgrade.

Update Location EPW.tsv

Has new dependency: Location Cooling Region.

LHS sampling

• Use discrete sampling instead of continuous; alternatively, convert continuous sample value to discrete sample number
• Implement quota-based sampling to map from discrete sample number to option.
• Verify LHS sampling does what we want.

Migrate to PAT 2.0

PAT 2.0 development to support ResStock

• Use of docker & OS 2.0 (will fix #12 and #38)
• Implementation of diagonal sampling
• Cannot specify integer_sequence distribution for pivot variable
• number_of_samples not available in the runner
• Allowing measures to be brought into the project multiple times (to be used with different arguments)
• Use results CSV for project reporting measures in algorithmic mode
• Allow relative path for resources so PAT project can be easily shared
• Unable to download large SQL output files
• Can't run new laptop on AWS
• Can't run national project -- zip too large? (Moved weather files to s3 bucket zip file downloaded by worker init script)
• Integer sequence error running the analysis
• Bug when duplicating ApplyUpgrade measure
• Implementation of datapoint initialization/finalization scripts
• Ability to skip N/A simulations (#37)
• Implementation of server initialization/finalization scripts

ResStock development

• Create PAT 2.0 project
• Switch from use of runner.past_results to results.step
• Add outputs to PAT project (and reporting measures where possible)
• Use relative paths as appropriate
• Check if DDYs are being sent to the server
• Fix weight calculation (use integer_sequence max value rather than algorithm number_of_samples)
• Use s3 bucket & init script for weather files
• Hook up sampling as datapoint init script
• Clean out datapoint dirs as datapoint final script
• Fix output variables as needed (once OS 2.2 is out)
• Add option name argument to ApplyUpgrade measure since there is nowhere else to store this in PAT? (PAT feature request)
• Hook up post-processing server final script

cc @ejhw @joseph-robertson

Propane air loop HVAC band-aid

Temporary fix in place. Need to revert when https://github.com/NREL/OpenStudio-BEopt/issues/114 is closed.

Copy empty seed model in rake task

Will ensure we stay in synch with OpenStudio-BEopt repo.

Existing csv for retrofits

Currently needs to be in a standalone directory due to a bug that doesn't allow directly specifying the file location. When the bug is fixed, change the "Other Library Files" section in res_stock_pnw_upgrades.xlsx and uncomment the code in perform_integrity_checks() in util.rb.

NREL/OpenStudio-analysis-gem#21

Change Custom Region definitions

I think we'd like to change the following regions to make them more ordered by climate. Some of our materials (characteristics spreadsheet for external users) already have this change made.

New England: from 4 to 3
Great Lakes: from 5 to 4
Mountain North: from 3 to 5
cc @shorowit

Geometry house size tsv

From AHS data, not RECS.

Dependencies:

• Location Census Division
  • 'New England', 'East North Central', 'Middle Atlantic', 'Mountain - Pacific', 'South Atlantic - East South Central', 'West North Central', 'West South Central'
• Vintage
  • <1950, 1950s, 1960s, 1970s, 1980s, 1990s, 2000s

@ejhw

House size

Use location/vintage specific house sizes for each house size bin? (Backup plan: increase the number of house size bins.)

Add EPWs for PNW regions

Already doing this for national-scale version, just need data defined for PNW version.

National-scale output scatter plots

Measured consumption from RECS.

• Are they weather-normalized values?

RBSA queries

Need to complete RBSA querying for input probability distributions.

Data: Improve HVAC efficiency probability distributions

"About 50% of furnace sales in 2015 met or exceeded the 92% efficiency level."
http://www.appliance-standards.org/blog/doe-takes-major-step-furnace-efficiency-standard

Script to compare RBSA consumption data to simulation results

• Method to query TMY3-normalized RBSA consumption data (Measured data)
• Method to retrieve simulated energy use from analysis results (Predicted data)
• Per house electricity/gas plots, sliced by:
  • Location Heating Region
  • Vintage
  • Heating Fuel
  • Location Heating Region and Vintage
• Plots of electricity + gas, sliced by:
  • Location Heating Region
  • Vintage
  • Heating Fuel

To be reviewed by @ejhw.

Duct options

There are very high weighting factors for "In Finished Space".

In one of Eric's recent commits (09c04e6), he added a comment regarding when we assume ducts are in finished space. Sounds like we need to revisit?

@jrobert1 @ewilson

Prefix options in txt files

Prefix option names in probability distribution text files with "Option=". This will allow additional user-specified columns (notes, house counts/weights, etc.) to be stored in the files without causing problems.

Duplicate schedules

Some schedules are appearing twice (e.g., "residential bath schedule" and "residential bath schedule 1"), with one of them not being referenced by any other objects. Need to figure out why and prevent the duplicate.

Federal poverty level tsv

From AHS data, not RECS.

Dependencies:

• Location MSA CD
• Vintage
  • <1950, 1950s, 1960s, 1970s, 1980s, 1990s, 2000s
• Geometry House Size
  • 0-1499, 1500-2499, 2500-3499, 3500+
• HVAC System Cooling Type
  • Central, Room, None

@ejhw

Rows with no house counts

For rows in the tsv files that have no house counts, we currently distribute the probability equally across all available options.. Instead, let's add a "null" option and assign 1.0 to this option.

Values for choice arguments

Had a bug where we were passing "3" for the # of bathrooms argument, but the choices were "1", "2", and "3+". As far as I can tell, OpenStudio didn't complain and simply used our default value (which was "2"). Would have thought that runner.validateUserArguments(arguments(model), user_arguments) in the measure would catch this.

Need to further look into how OS handles this and determine whether we need better error checking on our side. Could be similar problems with other arguments.

PNW HVAC modeling challenges

• Wood/pellet stoves as primary/secondary: 126/545 samples (RBSA shows no backup systems)
• Dual fuel heat pumps: 18 samples
• GSHP - 14 samples
• Radiant floor / heated slab
• Model PTACs separately or model as RoomAC? How many PTACs in non-multifamily?
• Need way to specify Electric Baseboard for MSHP homes
• Electric space heaters (JR: pretty sure we're modeling 'pluginheater' as Electric Baseboard (?))

Apply upgrades logic

Allow upgrades to apply to subset of existing housing stock.

• Initial implementation
• Need to handle upgrades that don't apply. Using runner.registerAsNotApplicable and return False doesn't prevent simulations from running and output in the analysis csv. Using runner.registerError and return False does prevent this, but then the datapoint shows up as a failed simulation. Andrew Parker: "I think you could export the final condition value (success/error/NA) to the spreadsheet then check this during post-processing and disregard the NA ones." However, this doesn't prevent lots of additional simulations from being run.
• Packages currently allow individual options to apply based on their own logic. Add ability for logic to apply to the entire package?
• Allow "option is not XXXX" in addition to the current "option is XXXX" functionality?

None Heating Systems

We have moderate percentages of buildings with no HVAC heating systems in the PNW. I assume this is because of systems that we can't currently model? We really shouldn't map these to None, because we're ending up with building simulations without heating.

I think we should either:

1. Add options for these other technologies (and model them with the closest technology approximation)
2. Ignore these buildings and redistribute the probabilities of non-None options to 100% (and perhaps reduce the total house count)

Thoughts?

cc @joseph-robertson @craigch99 @ejhw

Utility bill calculations

Use hourly output timeseries data and SAM SDK for utility bill calculations.

• Reporting measure for creating hourly output csv
• Be able to require ffi
  • Right now ffi is not packaged with openstudio; however, can run unit tests.
• Call utilityrate3 SAM module with appropriate inputs
  • Inputs from api calls to openei urdb
• Register the calculated energy, demand, and utility bill values somewhere

Flexible parameter resolution for vintage, etc.

We have a concept of hierarchical/disparate geographies (i.e., census tracts, states, regions) that can be used for defining probability distributions. Can we do something similar for non-geographic parameters? e.g., 1960s+1970s instead of separate 60s and 70s rows. This would be helpful for infiltration.

---

• Add vintage bins compatible with infiltration.tsv
• Add vintage bins compatible with FPL.tsv

Missing DDY info

Not every EPW we use for ResStock has DDY info. Will copy DDY info from a nearby location for now to bypass errors, but need to think about a longer term solution.

Check for extra combinations in probability files

See https://github.nrel.gov/jrobert1/rbsaquery/issues/33. We currently ensure that every combination of dependencies exist but don't check if there are extra/duplicates. We should give an error if this is found.

Allow measure args across parameters

If we allow args for a measure to be set across multiple parameters, it would eliminate the need for "aggregation" parameters like Airflow.tsv and Geometry.tsv.

Rebuilt vs. Original model sim results

The simulation results for the Rebuilt model (used for evaluating upgrades) is not identical to those from the Original model (for the existing housing stock). I've verified that the same set of OS measures/arguments are being used. Oddly, it only appears to be the water heating end use that differs. Need to figure out why this is.

Upgrade costing

• Add arguments to ApplyUpgrade measure to allow 1 or more cost values & multipliers for each option; runner.registerValue this information for upgrade options that apply.
• In SimulationOutputReport reporting measure, obtain cost multiplier values (from eplusout.sql or, if needed, from the model) and combine with cost values. runner.registerValue the total upgrade cost.
• For upgrade packages, only apply costs to those individual options that were applied.
• Add argument for lifetime (years) to Apply Upgrade meta measure
• Need a way to handle incremental costs (e.g., attic insulation going from R-20 to R-60 vs R-30 to R-60). As a workaround, one could use a package with multiple R-60 options, each of which has a different starting option apply logic and thus cost. #848

Consolidate H1 regions?

@cchriste proposes that we consolidate H1C1 OR, H1C1 WA, H1C2, and H1C3 into a single H1 region. Decision pending.

cc @jrobert1 @ewilson

Water Heater query

I recommend skipping these options, as they have near zero probabilities:

Oil Tankless
Electric HPWH
Electric Tankless
@cchriste @ewilson

Percent space conditioned band-aid

Implemented handling for % Conditioned (for Room ACs and MSHPs) in the reporting measure as a temporary band-aid. Should be reverted when https://github.com/NREL/OpenStudio-BEopt/issues/54 is closed.

Script to collect hourly output on server

• zip
• pandas hdf5
  • datapoint_id | Time | enduse_id | value
  • length of table is datapoint_ids * 8,760 * enduse_ids
  • convert string timestamps to epoch time?
• h5py hdf5
  • store numpy arrays in format of original csv
  • store column names in attrs
  • convert string timestamps to epoch time?

@nmerket to review /resources/collect.py.

AWS instances running out of space

Occurring on AWS even with c3.8xlarge instance types. Write reporting measure that deletes or compresses various simulation files?

PNW Heating and Cooling Setpoints

Below I'm comparing setpoints from audit data (HeatTemp, HeatTempNight, ACTemp, ACNight) to indoor temperature from meter data (IDT).

For each metered home, I used a very simple clustering approach (with n=2 clusters) to identify a "min" setpoint and a "max" setpoint. I used DEC, JAN, FEB data for the heating setpoint min and max clusters, and JUN, JUL, AUG for the cooling setpoint min and max clusters.

In general, I think the resident-reported setback for heating aligns with the meter data better than the setup for cooling.

Heating

Cooling

@shorowit @craigch99

HVAC options

Need to handle combined heating/cooling systems (i.e., heat pumps).

• Add HVAC measures into workflow
• Update probability distributions after RBSA querying is complete
• Update OpenStudio-server to use OpenStudio 1.11.5 or later (e.g., for 1-spd ASHPs)
• Update approach for setpoints once NREL/OpenStudio-Beopt#19 is implemented.

Data: Add diversity to infiltration

Currently probability distributions for both are "single value".