The BuildingSync-Gem is a repository of helpers for reading and writing BuildingSync XML files, and for using that data to drive energy simulations of the subject building. See full documentation on RubyDoc.

All of the following are supported:

  • convert BuildingSync XML file into:

    • an OpenStudio Baseline model
    • an OpenStudio workflow for each scenario defined in the XML file
  • enables simulation of the baseline model and all workflows and

  • insert simulation results back into the Building XML file.


Add this line to your application's Gemfile:

gem 'buildingsync'

And then execute:

$ bundle

Or install it yourself as:

$ gem install 'buildingsync'


All of the features described above are provided by the translator class, as shown in the following sample code:

building_sync_xml_file_path = 'path/to/bsync.xml'
out_path = 'path/to/output_dir'

# initializing the translator 
translator =, out_path)

# generating the OpenStudio Model and writing the osm file.
# path/to/output_dir/SR and path/to/output_dir/in.osm created

# generating the OpenStudio workflows and writing the osw files
# auc:Scenario elements with measures are turned into new simulation dirs
# path/to/output_dir/scenario_name

# run all simulations

# gather the results for all scenarios found in out_path,
# such as annual and monthly data for different energy
# sources (electricity, natural gas, etc.)

# Add in UserDefinedFields, which contain information about the
# OpenStudio model run 

# write results to xml
# default file name is 'results.xml' 
file_name = 'abc-123.xml' 


Check out the repository and then execute:

$ bundle install

$ bundle exec rake


The documentation of the BuildingSync-Gem is done with Yard ( To generate the documentation locally do the following:

 $ gem install yard

 $ yardoc - 

Updating published documentation

Publish documentation for each release:

  1. Tag release on GitHub
  2. Go to and click Add Project in the upper right
  3. Input the git address: git://github/BuildingSync/BuildingSync-gem.git
  4. Input the release tag for the desired version, eg: v0.2.0
  5. Click Go
  6. Profit


  1. Update
  2. Run bundle exec rake rubocop:auto_correct
  3. Update version in /lib/buildingsync/version.rb
  4. Create PR to main, after tests and reviews complete, then merge
  5. Locally - from the main branch, run bundle exec rake release
  6. On GitHub, go to the releases page and update the latest release tag. Name it “Version x.y.z” and copy the CHANGELOG entry into the description box.