Skip to content

Buildingsync gem 2.0 #158

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
haneslinger wants to merge 28 commits into
base: develop
Choose a base branch
from
Open

Buildingsync gem 2.0 #158

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
f243ba3
Create write_baseline_osw
haneslinger May 7, 2025
c98975c
Update dependencies
haneslinger Nov 17, 2025
68a8afe
Urdate workflow_maker
haneslinger Nov 17, 2025
2a83c93
Clean
haneslinger May 30, 2025
dfe729d
Delete model writing
haneslinger Jun 2, 2025
1ffd2d0
Remove build_zone_hash
haneslinger Jun 2, 2025
7362d35
Remove check building fraction
haneslinger Jun 3, 2025
9702752
Delete systems
haneslinger Jun 4, 2025
0ddc764
Remove unneeded helpers
haneslinger Jun 4, 2025
4d1a4ff
Remove WorkflowMakers @workflow
haneslinger Jun 4, 2025
f26a8c0
Delete some tests
haneslinger Jun 4, 2025
18eabb5
Add small office
haneslinger Nov 17, 2025
df7903d
Read climate zone
haneslinger Nov 17, 2025
912de8b
Add small office to tests
haneslinger Jun 24, 2025
02b6643
Populate principal_HVAC_system_type
haneslinger Jun 27, 2025
c171f3c
Add system measures and remove unneeded class attrs and params
haneslinger Nov 17, 2025
950a485
Fix weatherfile retrival and other clean up
haneslinger Nov 17, 2025
c66a72e
Fix Tests
haneslinger Nov 17, 2025
65c6178
Add all current tests
haneslinger Nov 17, 2025
bdd1022
Update dependencies and Readme
haneslinger Jan 12, 2026
ad82383
Update license
haneslinger Jan 13, 2026
8f81458
Fix tests
haneslinger Feb 23, 2026
98ebb05
Rename gem and update readme
haneslinger Mar 20, 2026
986f17c
Update lib/buildingsync/bcl_weather_file_downloader.rb
kflemin Apr 2, 2026
28923b4
copilot suggestions and added documentation
kflemin Apr 2, 2026
81e6119
fix merge
kflemin Apr 2, 2026
7806bd5
small fixes
kflemin Apr 2, 2026
1edc954
fix
kflemin Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 6 additions & 24 deletions .github/workflows/continuous_integration.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ on:
jobs:
model_articulation_tests:
name: Model Articulation Tests
container: nrel/openstudio:3.4.0
container: nrel/openstudio:9.0
runs-on: ubuntu-latest
steps:
- name: Checkout Code
Expand All @@ -26,24 +26,9 @@ jobs:
- name: Building Spec
run: bundle exec rspec spec/tests/model_articulation_test/building_spec.rb
if: always()
- name: Envelope System Spec
run: bundle exec rspec spec/tests/model_articulation_test/envelope_system_spec.rb
if: always()
- name: Facility Spec
run: bundle exec rspec spec/tests/model_articulation_test/facility_spec.rb
if: always()
- name: HVAC System Spec
run: bundle exec rspec spec/tests/model_articulation_test/hvac_system_spec.rb
if: always()
- name: Loads System Spec
run: bundle exec rspec spec/tests/model_articulation_test/loads_system_spec.rb
if: always()
- name: Lighting System Spec
run: bundle exec rspec spec/tests/model_articulation_test/lighting_system_type_spec.rb
if: always()
- name: SHW System Spec
run: bundle exec rspec spec/tests/model_articulation_test/service_hot_water_system_spec.rb
if: always()
- name: Site Spec
run: bundle exec rspec spec/tests/model_articulation_test/site_spec.rb
if: always()
Expand All @@ -60,7 +45,7 @@ jobs:

translator_tests:
name: Translator Tests
container: nrel/openstudio:3.4.0
container: nrel/openstudio:3.9.0
runs-on: ubuntu-latest
steps:
- name: Checkout Code
Expand All @@ -69,11 +54,8 @@ jobs:
run: |
gem install bundler -v 2.4.22
bundle install
- name: Translator Example Spec
run: bundle exec rspec spec/tests/translator_spec.rb
if: always()
- name: Translator Sizing Run Spec
run: bundle exec rspec spec/tests/translator_sizing_run_spec.rb
- name: Translator Write OSW Spec
run: bundle exec rspec spec/tests/translator_write_osw_spec.rb
if: always()
- name: Translator Scenario Generation Specs
run: bundle exec rspec spec/tests/translator_scenario_generation_spec.rb
Expand All @@ -84,7 +66,7 @@ jobs:

report_and_scenario_tests:
name: Report and Scenario Tests
container: nrel/openstudio:3.4.0
container: nrel/openstudio:3.9.0
runs-on: ubuntu-latest
steps:
- name: Checkout Code
Expand Down Expand Up @@ -117,7 +99,7 @@ jobs:

other_specs:
name: Other Tests
container: nrel/openstudio:3.4.0
container: nrel/openstudio:3.9.0
runs-on: ubuntu-latest
steps:
- name: Checkout Code
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/deploy.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ jobs:
- name: Setup Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: '2.7'
ruby-version: '3.2.2'

- name: Install and Build
run: |
Expand Down
4 changes: 1 addition & 3 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,7 @@ lib/measures/.rubocop.yml
lib/measures/building_sync_to_openstudio/tests/output

# OSW tests for gem
osw_test/generated_files
osw_test/run
osw_test/out.osw
osw_test

spec/files/filecomparison/in.idf
spec/files/filecomparison/in.osm
Expand Down
29 changes: 5 additions & 24 deletions Gemfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,27 +5,8 @@ source 'http://rubygems.org'
gemspec

# Local gems are useful when developing and integrating the various dependencies.
# To favor the use of local gems, set the following environment variable:
# Mac: export FAVOR_LOCAL_GEMS=1
# Windows: set FAVOR_LOCAL_GEMS=1
# Note that if allow_local is true, but the gem is not found locally, then it will
# checkout the latest version (develop) from github.
allow_local = ENV['FAVOR_LOCAL_GEMS']

if allow_local && File.exist?('../openstudio-common-measures-gem')
gem 'openstudio-common-measures', path: '../openstudio-common-measures-gem'
else
gem 'openstudio-common-measures', github: 'NREL/openstudio-common-measures-gem', tag: 'v0.6.1'
end

if allow_local && File.exist?('../openstudio-model-articulation-gem')
gem 'openstudio-model-articulation', path: '../openstudio-model-articulation-gem'
else
gem 'openstudio-model-articulation', github: 'NREL/openstudio-model-articulation-gem', tag: 'v0.6.1'
end

if allow_local && File.exist?('../openstudio-ee-gem')
gem 'openstudio-ee', path: '../openstudio-ee-gem'
else
gem 'openstudio-ee', github: 'NREL/openstudio-ee-gem', tag: 'v0.6.0'
end
# To favor the use of local gems, uncomment these lines
# gem 'openstudio-extension', path: '../OpenStudio-extension-gem'
# gem 'openstudio-common-measures', path: '../openstudio-common-measures-gem'
# gem 'openstudio-model-articulation', path: '../openstudio-model-articulation-gem'
# gem 'openstudio-ee', path: '../openstudio-ee-gem'
4 changes: 2 additions & 2 deletions LICENSE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
OpenStudio(R), Copyright (c) 2008-2022, Alliance for Sustainable Energy, LLC. All rights reserved.
BuildingSync(R), Copyright (c) 2015-2022, Alliance for Sustainable Energy, LLC. All rights reserved.
OpenStudio(R), Copyright (c) 2008-2026, Alliance for Energy Innovation, LLC. All rights reserved.
BuildingSync(R), Copyright (c) 2015-2026, Alliance for Energy Innovation, LLC. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted
provided that the following conditions are met:
Expand Down
151 changes: 72 additions & 79 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,101 +1,99 @@
# BuildingSync
# BOSS - BuildingSync OpenStudio Simulator

![BuildingSync-gem](https://github.com/BuildingSync/BuildingSync-gem/actions/workflows/continuous_integration.yml/badge.svg?branch=develop)
BuildingSync OpenStudio Simulator (BOSS) takes in BuildingSync files, creates OpenStudio workflows from their contents, and runs those workflows to create models.

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 [here](https://buildingsync-gem.buildingsync.net).

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
* enable simulation of the baseline model and all workflows and
* insert simulation results back into the Building XML file.

## Installation
1. Install OpenStudio 3.10. Check installation with
```console
🌟 openstudio --version
3.10.0+ce46db07de
```

The BuildingSync Gem requires installation of OpenStudio, specifically [OpenStudio v3.4.0](https://openstudio-builds.s3.amazonaws.com/index.html?prefix=3.4.0/).
The newer versions of OpenStudio have minor breaking changes that have not been addressed in this repository yet. After OpenStudio is
installed, then export the path of the folder that contains the openstudio.rb file to RUBYLIB environment variable
(e.g., `export RUBYLIB=/Applications/OpenStudio-3.4.0/Ruby`)
2. Set enviroment variable `RUBYLIB` to the location of your openstudio installation. Check env var with:
Copy link

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spelling: "enviroment" should be "environment".

Suggested change
2. Set enviroment variable `RUBYLIB` to the location of your openstudio installation. Check env var with:
2. Set environment variable `RUBYLIB` to the location of your openstudio installation. Check env var with:

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The README has a spelling error: enviroment -> environment (and related sentence reads awkwardly). Fixing this improves documentation clarity.

Suggested change
2. Set enviroment variable `RUBYLIB` to the location of your openstudio installation. Check env var with:
2. Set the environment variable `RUBYLIB` to the location of your OpenStudio installation. Check it with:

Copilot uses AI. Check for mistakes.
```console
🌟 echo $RUBYLIB
/Applications/OpenStudio-3.10.0/Ruby
```

After installing OpenStudio and setting the environment variable, then add this line to your application's Gemfile:
```ruby
gem 'buildingsync', '0.2.1'
```
3. From local repo, bundle install

And then execute:
```bash
bundle install
```

Or install it yourself as:
```bash
gem install 'buildingsync'
```
```bash
🌟 bundle install
```

## Usage

All of the features described above are provided by the translator class, as shown in the following sample code. There
are also BuildingSync Gem example files in [this repository](https://github.com/BuildingSync/BuildingSync-gem-examples).

BOSS uses its `Translator` class to 1) write openstudio workflows and 2) run those workflows.
```ruby
require 'buildingsync/translator'

building_sync_xml_file_path = 'path/to/bsync.xml'
out_path = 'path/to/output_dir'
# init translator
xml_file_path = "BuildingEQ-1.0.0_gemtest.xml"
output_dir = "output"
translator = BuildingSync::Translator.new(xml_file_path, output_dir, nil, "ASHRAE90.1")

# initializing the translator
translator = BuildingSync::Translator.new(building_sync_xml_file_path, out_path)
# create baseline workflow from buildingsync file
translator.write_baseline_osw
expect(File.exist?("#{output_dir}/baseline/in.osw")).to be true

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

# 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
translator.write_osws

# run all simulations
translator.run_osws

# gather the results for all scenarios found in out_path,
# such as annual and monthly data for different energy
# sources (electricity, natural gas, etc.)
translator.gather_results(out_path)
# create baseline model from workflow
translator.run_baseline_osw
expect(File.exist?("#{output_dir}/baseline/out.osw")).to be true
expect(File.exist?("#{output_dir}/baseline/in.osm")).to be true
```

# Add in UserDefinedFields, which contain information about the
# OpenStudio model run
translator.prepare_final_xml
The file `workflow_maker.rb` does all of the actual writing to the osw. Each function writes one measure. Heres an overview of how each measure is populated.

[set_run_period]: https://github.com/NatLabRockies/openstudio-common-measures-gem/blob/v0.12.3/lib/measures/set_run_period/README.md
[ChangeBuildingLocation]: https://github.com/NatLabRockies/openstudio-common-measures-gem/blob/v0.12.3/lib/measures/ChangeBuildingLocation/README.md
[create_bar_from_building_type_ratios]: https://github.com/NatLabRockies/openstudio-model-articulation-gem/blob/v0.12.2/lib/measures/create_bar_from_building_type_ratios/README.md
[create_typical_building_from_model]: https://github.com/NatLabRockies/openstudio-model-articulation-gem/blob/v0.12.2/lib/measures/create_typical_building_from_model/README.md
[SetLightingLoadsByLPD]: https://github.com/NatLabRockies/openstudio-common-measures-gem/blob/v0.12.3/lib/measures/SetLightingLoadsByLPD/README.md
[set_electric_equipment_loads_by_epd]: https://github.com/NatLabRockies/openstudio-common-measures-gem/tree/v0.12.3/lib/measures/set_electric_equipment_loads_by_epd
[openstudio_results]: https://github.com/NatLabRockies/openstudio-common-measures-gem/blob/v0.12.3/lib/measures/openstudio_results/README.md

| Measure | Argument | Will error if Unset | Description |
|----------------------------------------|-------------------------|:-------------------:|-----------------------------------------------------------------------------------------------------------------------------------|
| [set_run_period] | | | |
| | timesteps_per_hour | | Hard Coded to `1` |
| | begin_date | | Hard Coded to `2019-01-01` |
| | end_date | | Hard Coded to `2019-12-31` |
| [ChangeBuildingLocation] | | | |
| | weather_file_name | X | set via `set_weather_and_climate_zone` from the given weather file, or the building's climate zone, or city and state. |
| | climate_zone | | The site's climate zone, set via `determine_climate_zone`, which chooses either the `CaliforniaTitle24` or `ASHRAE` climate zone |
| [create_bar_from_building_type_ratios] | | | |
| | bldg_type_a | X | set via `building.get_building_type`, which in turn is set via `set_bldg_and_system_type_for_building_and_section` |
| | total_bldg_floor_area | X | set via `building.total_bldg_floor_area`, which is set via `read_floor_areas` |
| | floor_height | | set via `get_floor_to_floor_height`. Set to the `floor_to_floor_height` of the largest building section |
| | num_stories_above_grade | | set via `building.num_stories_above_grade`, which is set via `read_stories_above_and_below_grade` |
| | num_stories_below_grade | | set via `building.num_stories_below_grade`, which is set via `read_stories_above_and_below_grade` |
| | building_rotation | | always set to 0, not read from BuildingSync file |
| | template | X | set via `building.get_standard_template`, which is set via `set_standard_template` |
| | ns_to_ew_ratio | | set via `building.ns_to_ew_ratio`, which is set via `set_ns_to_ew_ratio` |
| | wwr | | set via `building.wwr`, which is set via `set_building_form_defaults` |
| | party_wall_fraction | | set via `building.party_wall_fraction`, which is always set to zero |
| | story_multiplier_method | | set to None |
| [create_typical_building_from_model] | | | |
| | template | X | set via `building.get_standard_template`, which is set via `set_standard_template` |
| | system_type | | set to `facility.get_principal_HVAC_system_type` |
| | add_swh | | set to `facility.get_principal_HVAC_system_type` |
| | add_hvac | | set to `facility.get_principal_HVAC_system_type` |
| [SetLightingLoadsByLPD] | | | |
| | lpd | | set to `facility.get_total_installed_power` |
| [set_electric_equipment_loads_by_epd] | | | |
| | epd | | set to `facility.get_total_installed_power * 1000 / building.total_floor_area` |
| [openstudio_results] | | | |

# write results to xml
# default file name is 'results.xml'
file_name = 'abc-123.xml'
translator.save_xml(file_name)
```

## Testing

Check out the repository and then execute:

```bash
bundle install
bundle exec rake
bundle exec rspec ./spec/tests/translator_write_osw_spec.rb
```

## Documentation

The documentation of the BuildingSync-Gem is done with Yard (https://yardoc.org)
To generate the documentation locally do the following:

```bash
gem install yard
SITEMAP_BASEURL=https://buildingsync-gem.buildingsync.net bundle exec yard doc --plugin sitemap
```

Documentation for the develop branch is automatically released when code is merged into the branch.
This only runs only files worth of tests, which are integration tests very similar to the code in the usage section. The gem has under gone major rewrites and many of the other tests use dead and/or delete code. Further clean up and testing is underway.

# Releasing

Expand All @@ -105,8 +103,3 @@ Documentation for the develop branch is automatically released when code is merg
1. Create PR to main, after tests and reviews complete, then merge
1. Locally - from the main branch, run `bundle exec rake release`
1. 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.

# TODO

* [ ] Support BuildingSync 2.3.0
* [ ] Update to OpenStudio version 3.2.0
Loading
Loading