Thermal Bridging & Derating (TBD)

An OpenStudio Measure that first autodetects major thermal bridges (like balconies, parapets and corners) in an OpenStudio model (.osm), and then derates outside-facing, opaque surface constructions (walls, roofs and exposed floors). It interacts with the OpenStudio SDK and relies on AutomaticMagic's Topolys gem, as well as rd2's OSut gem.

Building professionals and energy modellers are encouraged to first consult the online Guide - it provides an overview of the underlying theory, references, suggested OpenStudio workflows, etc. Users can download the latest TBD version directly from the Guide itself, or under releases, or via NREL's BCL (search for "bridging" or "rd2"). Questions can be posted on UnmetHours - a very useful online resource for OpenStudio users. TBD is also available as a Ruby gem - add:

gem "tbd", git: "https://github.com/rd2/tbd", branch: "master"

... in a bundled Measure development environment "Gemfile" (or preferably as a gemspec dependency), and then run:

bundle install (or 'bundle update')

Bugs or new feature requests for TBD should be submitted here, while those more closely linked to Topolys or OSut should be submitted here or here, respectively.

The installation and testing instructions in this section are for developers interested in exploring/tweaking a cloned/forked version of the source code. In an effort to lighten TBD as a Ruby gem, only the most basic tests are deployed in this repository. More detailed tests are housed in a dedicated TBD testing repo.

TBD is systematically tested against updated OpenStudio versions (since v3.0.0). The following instructions refer to OpenStudio v3.8.0, which requires Ruby v3.2.2. Earlier OpenStudio versions require Ruby v2.7.2. Adapt instructions for older (or newer) versions - see OpenStudio's compatibility matrix.

Either install Ruby using the RubyInstaller for Ruby 3.2.2 (x64), or preferably under a WSL2 environment. Run the following steps if going down the RubyInstaller route. From the command line, check that the ruby installation returns the correct Ruby version:

ruby -v

Install bundler, if not already installed:

bundler -v
gem install bundler -v 2.1

Install OpenStudio 3.8.0, or the OpenStudioApplication 1.8.0.

Create a new file C:\Ruby32-x64\lib\ruby\site_ruby\openstudio.rb (path may be different depending on the environment), and edit it so it points to your new OpenStudio installation:

require 'C:\openstudio-3.8.0\Ruby\openstudio.rb'

Verify your OpenStudio and Ruby configuration:

ruby -e "require 'openstudio'" -e "puts OpenStudio::Model::Model.new"

MacOS already comes with Ruby, but likely not the right Ruby version for the desired OpenStudio measure development environment. Instructions here show how to install Ruby v3.2.2 alongside MacOS's own Ruby version. Although no longer officially supported, instructions for an OpenStudio v2.9.1 setup is described here.

From a Terminal, install Homebrew - nice for package distribution and management. Using Homebrew, install rbenv (which allows users to manage multiple Ruby versions) and finally Ruby:

brew install rbenv
rbenv init
rbenv install 3.2.2

In the Terminal, check the Ruby version:

ruby -v

... should still report the current Ruby version used by MacOS. To ensure the right version is used for developing OpenStudio Measures, instruct rbenv to switch Ruby version locally within a user’s chosen directory (e.g. "sandbox380"):

mkdir ~/Documents/sandbox380
cd ~/Documents/sandbox380
rbenv local 3.2.2
ruby -v

… should now report the desired local Ruby version, to be used by default for anything under the "sandbox380" directory tree. To ensure both Ruby versions are operational and safe, run the following checkup twice - once from a user’s home (or ~/), then from within e.g. "sandbox380":

cd ~/
ruby -ropen-uri -e 'eval URI.open("https://git.io/vQhWq").read'
cd ~/Documents/sandbox380
ruby -ropen-uri -e 'eval URI.open("https://git.io/vQhWq").read'

If successful, one should get a Hooray! from both Ruby versions confirming valid communication with Rubygems.

Bundler is also required for managing Ruby gems and dependencies. With rbenv, the right Bundler version should have been installed. If for whatever reason it wasn't installed:

bundler -v
gem install bundler -v 2.4.10

Install OpenStudio 3.8.0, or the OpenStudio Application 1.8.0.

Create a new file ~/.rbenv/versions/3.2.2/lib/ruby/site_ruby/openstudio.rb (path may be different depending on the environment), and edit it so it points to your new OpenStudio installation:

require '/Applications/OpenStudio-3.8.0/Ruby/openstudio.rb'

Verify your local OpenStudio and Ruby configuration:

cd ~/Documents/sandbox380
ruby -e "require 'openstudio'" -e "puts OpenStudio::Model::Model.new"

Make sure you have latest version of git (e.g. through Homebrew).

Once done with either the Windows or MacOS setup, git clone the TBD repo, e.g. under "sandbox380". Run the basic tests below to ensure the measure operates as expected.

Run the following (basic) tests from TBD's root repository:

bundle update (or 'bundle install')
bundle exec rake libraries
bundle exec rake

Install Docker.

Pull the OpenStudio v3.8.0 Docker image:

docker pull nrel/openstudio:3.8.0

In the root repository:

docker run --name test --rm -d -t -v ${PWD}:/work -w /work nrel/openstudio:3.8.0
docker exec -t test bundle update
docker exec -t test bundle exec rake
docker kill test

Merci aux gouvernements du Québec et du Canada (CNRC, CanmetÉNERGIE).