Question-and-Answer Resource for the Building Energy Modeling Community
Get started with the Help page
Ask Your Question

How to write an OpenStudio measure to convert gbXML to IDF?

asked 2017-02-23 18:45:57 -0500

updated 2017-08-05 07:39:43 -0500

Here are a few questions about this topic:

1) Does the measure need to be written in Ruby? Is there any way to write it in C++ or Python maybe?

2) When a function (e.g. ForwardTranslator for EnergyPlus explained in here) is used in a measure, does it use the C++ source code under “openstudiocore/src” folder? (e.g. ForwardTranslator.cpp)

2-1)If yes, then how could I make sure that it has access to these source codes? Do I need to develop the measure under a certain folder within OpenStudio source code folder?

2-2) If not, then how does it understand what is the process of converting an OS file to IDF?

3) Is there any way to use the “gbXMLToidf” C++ source code directly in order to convert the gbXML to IDF? Is it necessary to write a measure first? (I know the application of OSW in CL, which is a new feature added to OS makes it easy to use different measures, but I’m just curious to evaluate different options I might have)

4) In general I’m confused between writing a “measure” and using available source codes in C++ under the “openstudiocore/src” folder. What is the difference between them? Do measures use these source codes or they work independently?


edit retag flag offensive close merge delete

2 Answers

Sort by » oldest newest most voted

answered 2017-02-23 21:43:44 -0500

updated 2017-02-23 22:19:14 -0500

I'll attempt to answer your questions but others might have some additional details about some of them.

Before starting to write measures it's a good idea to read the Measure Writing Guide.

  1. User's can interact with models through formal measures in the GUIs, which are written in Ruby, or more directly through the API with one of the language bindings for Ruby, C#, or Python. However, only Ruby and C# are fully supported, Python bindings require users to build OS from source code.

  2. See one definition of a language binding.

    • 2-1. No you don't need the source code to write measures. See the Measure Writing Guide.
    • 2-2. OpenStudio has methods in the SDK/API for translating OSM, IDF, and XML files.
  3. During a simulation OpenStudio uses the ForwardTranslator to translate the model to IDF for simulation using EnergyPlus. OpenStudio can also import IDFs via the GUI or the API, which uses the ReverseTranslator. Currently everything except the HVAC objects can be imported from an IDF. There isn't a gbXMLToidf method in the SDK, but there are ForwardTranslator and ReverseTranslator classes that have methods to convert to/from GBXML. See below for some untested code.

  4. No, user's do not need the source code for measures. The measures indirectly use the source code through the API and the Ruby bindings.

Here's an example of some untested code using the Ruby bindings outside of a formal measure that may work. See the Optional - Install Ruby instructions to enable this.

# OpenStudio Ruby Bindings
require 'openstudio'

# path to gbxml
xml_path = 'path/to/model.xml'

# gbxml to osm
reverse_translator =
model = reverse_translator.loadModel(xml_path)

# osm to idf
forward_translator =
idf = forward_translator.translateModel(model)

# save idf
idf_path = 'path/to/model.idf', true)
edit flag offensive delete link more


There is a gbXMLToIdf program (see here), but it actually does what this Ruby code does: translates the gbXML to an OpenStudio model and then writes that to an IDF (with error checking, etc.). This Ruby approach is the preferred path and will be easier to maintain than using the C++ directly (as the gbXMLToIDF program does).

Jason DeGraw's avatar Jason DeGraw  ( 2017-02-24 08:56:00 -0500 )edit

answered 2017-02-25 20:36:00 -0500

updated 2017-02-25 20:36:57 -0500

Thank you for your comprehensive response, Matthew. I put my takes here as a new answer. I'll pick your answer as the best answer though. I am using the OpenStudio source code and the following notes are based on that.

  1. So, one can still use other languages to write measures as long as proper language bindings are selected in CMake, while configuring and generating OpenStudio. More explanations could be find in here.

  2. & 4. The measures use the source codes indirectly through the API and respective language bindings (Ruby, Python, and etc.). However, I'm still not sure what are we referring to as "API". Is the the whole subroutines and modules used for generating the OpenStudio?

  3. I am still trying to set up Ruby to try the code provided by Mathew, however, I get some errors shown below that I might put it in a separate question, unless there is any quick comment on that in here. image description

As Jason and Matthew mentioned, using "gbXMLtoIDF" is still an option (the source code is also available when downloading the OpenStudio source code). However, after considering all options I'd rather go with writing a measure in Ruby and use OSW to automate running all the measures.

Thanks again, guys!

edit flag offensive delete link more



You're probably experiencing a Ruby version compatibility issue, since OS 1.4.1 to 1.14.0 uses Ruby 2.0. See the OpenStudio Version Compatibility Matrix. Also, I find IPython/Jupyter notebooks to be more useful than IRB. Just use the %%script ruby cell magic.

MatthewSteen's avatar MatthewSteen  ( 2017-02-25 22:14:29 -0500 )edit

As an FYI, you can use SageMathCloud to work with Jupyter Notebooks in the browser. They have a free tier available which might be enough for what you need.

anchapin's avatar anchapin  ( 2017-02-27 08:37:07 -0500 )edit

@anchapin how is SMC different than using an ipynb normally in the browser? No installation required?

MatthewSteen's avatar MatthewSteen  ( 2017-02-27 09:30:24 -0500 )edit

@MatthewSteen yes, with SMC there is no installation required, all you need to do is create an account and then you can start working with a Jupyter notebook.

anchapin's avatar anchapin  ( 2017-02-27 09:59:38 -0500 )edit

Your Answer

Please start posting anonymously - your entry will be published after you log in or create a new account.

Add Answer

Training Workshops


Question Tools



Asked: 2017-02-23 18:45:57 -0500

Seen: 1,011 times

Last updated: Feb 25 '17