Residential OpenStudio Measures

Unit Test Status:

Code Coverage:

This project includes OpenStudio measures used to model residential buildings.

This project is a work-in-progress. The models are not fully completed nor tested. These measures will eventually be posted on the Building Component Library

Progress is tracked in this spreadsheet.

Setup

A number of measures in this GitHub repository share the same resource files, found in the top-level resources directory. In order to run the measures, these resources need to be distributed to each measure. This process has been automated via a rake task (a task defined in the rakefile).

To be able to use the rakefile, download the OpenStudio installer from openstudio.net and, at a minimum, install the "Command Line Interface".

Follow the instructions below for Windows setup or Mac setup. Upon completion, you can now run rake update_resources to update the measures' resource files. You will want to perform this task anytime you do a clone or pull of the repository. You can also run rake -T to see the list of possible rake tasks.

Windows Setup

1. Install Ruby, making sure to use the version compatible with OpenStudio. Add the ruby location to your PATH.
2. Run gem install bundler. (If you get an error, you may have to issue the following: gem sources -r https://rubygems.org/ followed by gem sources -a http://rubygems.org/.)
3. Download DevKit at http://rubyinstaller.org/downloads/. Choose either the 32-bit or 64-bit version depending on which version of Ruby you installed. Run the installer and extract to a directory (e.g., C:\RubyDevKit). Go to this directory, run ruby dk.rb init, modify the config.yml file as needed, and finally run ruby dk.rb install.
4. Run bundler.

Mac Setup

Install Homebrew if you don't have it already.

Run brew doctor. It should give you, among other issues, a list of unexpected dylibs that you'll need to move for this to work such as:

Unexpected dylibs:
  /usr/local/lib/libcrypto.0.9.8.dylib
  /usr/local/lib/libcrypto.1.0.0.dylib
  /usr/local/lib/libcrypto.dylib
  /usr/local/lib/libklcsagt.dylib
  /usr/local/lib/libklcskca.dylib
  /usr/local/lib/libklcsnagt.dylib
  /usr/local/lib/libklcsrt.dylib
  /usr/local/lib/libklcsstd.dylib
  /usr/local/lib/libklcstr.dylib
  /usr/local/lib/libklmspack.0.1.0.dylib
  /usr/local/lib/libklmspack.0.dylib
  /usr/local/lib/libklmspack.dylib
  /usr/local/lib/libssl.0.9.8.dylib
  /usr/local/lib/libssl.1.0.0.dylib
  /usr/local/lib/libssl.dylib
  /usr/local/lib/libz.1.2.5.dylib
  /usr/local/lib/libz.1.2.6.dylib
  /usr/local/lib/libz.1.dylib
  /usr/local/lib/libz.dylib

Highlight and copy the list (without the header "Unexpected dylibs:). Run the following commands to move them to another location where they won't interfere.

mkdir ~/unused_dylibs
pbpaste | xargs -t -I % mv % ~/unused_dylibs

Install rbenv and required dependencies.

brew install openssl libyaml libffi rbenv

Initialize rbenv by running the command below and following the instructions to add the appropriate things to your ~/.bash_profile.

rbenv init

Install the appropriate ruby version.

cd path/to/repo
rbenv install `cat .ruby-version`

Add the path to the install ruby libraries top the bottom of your ~/.bash_profile

echo "export RUBYLIB=/Applications/OpenStudio-2.0.5/Ruby" >> ~/.bash_profile
echo "export ENERGYPLUS_EXE_PATH=\"/Applications/OpenStudio-2.1.0/EnergyPlus/energyplus-8.7.0\""

Install bundler and the libraries that bundler installs.

gem install bundler
bundle install

And finally

rake update_resources

New Construction Workflow for Users

The New Construction workflow illustrates how to build up a complete residential building model from an empty seed model. Note that some measures need to be called before others. For example, the Window Constructions measure must be called after windows have been added to the building. The list below documents the intended workflow for using these measures.

* Note: Nearly every measure is dependent on having the geometry defined first so this is not included in the table for readability purposes.

Retrofit Workflow for Users

Most of these measures were written to be reusable for existing building retrofits. The intended workflow is to create the existing building from an empty seed model in the same way as the New Construction Workflow. Once the existing building model has been created, the same measures can now be used to replace/modify building components as appropriate.

For example, while the dishwasher measure added a dishwasher to the model when applied to an empty seed model, the same measure, when applied to the existing building model, will replace the existing dishwasher with the newly specified dishwasher (rather than add an additional dishwasher to the model). This example could be used to evaluate an EnergyStar dishwasher replacement, for example. Alternatively, if the existing building was never assigned a dishwasher, then the measure would indeed add a dishwasher to the model.

Note that some measures are dependent on others. For example, if the Clothes Washer measure were to be applied to the existing building model, such that the existing clothes washer is replaced, the Clothes Dryer measure would also need to be subsequently applied to the existing building model so that its energy use, as dependent on the clothes washer, is correct.