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

SDK documentation in OS

asked 2015-12-21 05:00:46 -0600

ngkhanh gravatar image

updated 2015-12-21 09:43:30 -0600

Hello, 1)I am not sure about OS SDK currently has the coilsystem:DX:cooling or not ? in OS 1.10 The OUT.idf of an DX airloop has this one but i can not find it in SDK documentation. Have any resources about this ?

2) How to get name of a schedule (object) used in OS for examples the OS number of people and set other equipment object also use this object by measures? Thank

edit retag flag offensive close merge delete

2 Answers

Sort by ยป oldest newest most voted

answered 2015-12-21 14:27:38 -0600

updated 2015-12-30 11:54:30 -0600

To answer the second part most internal loads instances in OpenStudio have a method '.schedule' that returns an optional schedule. Below is a link to the SDK and how you would test if there is a schedule assigned, and get it if it exists. https://openstudio-sdk-documentation....

  schedule = lights_instance.schedule.get
  puts "#{} does not have a schedule assigned"

Updated: Below I added some guidance for using the API documentation.

The Developers section of the OpenStudio website links to the SDK Documentation. When you get to that page you will generally click on "model" for the current release. You can also look at last iteration. This is not specifically the "model object" but rather the API for all model objects (which just happens to have an object called "model" that has some methods).

image description

Once you are on the page for the model API you can start to type a class name in the search dialog near the top right. It auto completes as shown below where I'm search for Space.

image description

The screenshot below shows you all methods available directly to the space object.

image description

But the space is a sub-class so there are many methods from parent classes. The screenshot below shows you how to see a tree of parent classes.

image description

You can click on a parent to specifically see methods for the parent class, or you can click on "List of all members" to see a flat view of all methods (included inherited methods from parent classes like This is shown in the screenshot below.

image description

In the documentation you can see if a method that gets something out of the model returns an optional value or not. If it does have an optional value you want to use 'if value.is_initialized" or "if not value.empty?" first to see if the optional has anything or not. If it passes that test then to actually get the value you need to do "value.get". If you try to do "value.get" on an object that doesn't have a value you get a ruby error. That is why you first check if it has a value before you get it.

Few bonus items. You can click "Object Index" under "Objects" to view list of all objects. You can click an object to go to its SDK documentation. image description

If you are really daring you can view this as a tree by going to "Object Hierarchy". Make sure you scroll down to see the content as shown below. You can use a search with your browser to find specific objects.

image description

And here is a look at OS:Material and all the its sub-classes.

image description

edit flag offensive delete link more


Thank a lot for your answer but how to get the schedule which is applying for a space and a space type so that apply for equipment availability schedule. I get confused between .get and "Model.getSpaces" ? how different between them ? Need getSomething always to have Model. object ? How should i need to do when 1 thermal zone have more than 1 spaces to get schedules applying for that thermal zone ?

ngkhanh gravatar image ngkhanh  ( 2015-12-23 11:38:21 -0600 )edit

You may want to go through the Run section of the measure writing guide to learn more about using the API. Different objects have different methods. Not everything is returned from model. For example AirLoopHVAC has a method 'availabilitySchedule'. First you get the air loop you want, or loop through all, and then call this method.

David Goldwasser gravatar image David Goldwasser  ( 2015-12-28 10:50:30 -0600 )edit

The relation and syntax between classes and model objects in SDK and Measuring writing guide are very complex for me. Perhaps i need to try more get it. 1/ There is any source for carefully standard syntax explanation like .get, .name, initialized, ..... and difference with standard object in SDK document like getDefaultScheduleSet, ..... The measuring guide is just brief demonstration about them When i need call Openstudio::model::... and just Model/object.sch.... ? in other words, "." vs "::"

ngkhanh gravatar image ngkhanh  ( 2015-12-28 11:38:47 -0600 )edit

See updated answer above. It walks you through how to use the documentation through some screenshots.

David Goldwasser gravatar image David Goldwasser  ( 2015-12-30 11:37:26 -0600 )edit

answered 2015-12-21 09:49:47 -0600

I can answer part 1. In OS the DX cooling coils are allowed directly on the AirLoopHVAC structure. For example you can drag CoilCoolingDXSingleSpeed directly onto a node in the AirLoopHVAC supply path and everything will "just work". On the other hand, in E+ the DX coils need to be "wrapped" in CoilSystemDXCooling or a unitary system. OpenStudio is aware of this E+ requirement and wraps the DX coil in the coil system automatically when the idf file is created.

If you want to use some of the features introduced by the coil system such as the advanced dehumidification modes, I suggest that you consider the AirLoopHVACUnitarySystem object that is exposed in the OpenStudio API. You can wrap your DX coil as a single component in the unitary and achieve the same goals.

edit flag offensive delete link more


I used it before but not able to get result. although the Unitary air loop has latent load and DOAS coil option but there is no option for multi-zone high humidity set point manager as multizone DOAS required. May you give me an example which success control humidity for multizone zone with Unitary airloop ventilationRequriement sizing . i am really appreciated. My setting, and My result

ngkhanh gravatar image ngkhanh  ( 2015-12-21 11:02:58 -0600 )edit

Hmmm. Multi-zone may present a problem. AirLoopHVACUnitarySystem does have a Control Type field that lets you specify "Setpoint" operation. I think it is feasible to use this mode with humidity setpoint managers, but I admit I have never done it myself.

Kyle Benne gravatar image Kyle Benne  ( 2015-12-21 13:54:40 -0600 )edit

I have used AirLoopHVACUnitarySystem in Setpoint mode more generally though, with simple temperature based setpoint managers. This mode essentially circumvents the unitary's built in control logic making it more like a traditional coil wrapper. The one problem is that OpenStudio's public API and the user interface does not expose the control mode field. I don't like to recommend this, but you could edit the osm file directly to manipulate this field.

Kyle Benne gravatar image Kyle Benne  ( 2015-12-21 13:58:05 -0600 )edit

We use the setpoint mode in the CBECC translator using private methods that you can't see. I originally didn't expose this field in the public interface because I thought it had the potential to let users "shoot themselves in the foot". Now I think it is time to make it an officially supported feature throughout the public interfaces. It should be clear by now, that I'm really trying to consolidate things around this unitary in an effort to reduce the number of types and multiple ways of doing the same thing.

Kyle Benne gravatar image Kyle Benne  ( 2015-12-21 13:59:28 -0600 )edit

So have you had any recommendation for me to implement that object in OS in case ? What is CBECC translator and may i get it ? i focus on the result not the procedure. May a Energyplus measure will work with this case ? Thanks

ngkhanh gravatar image ngkhanh  ( 2015-12-22 09:03:29 -0600 )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

1 follower


Asked: 2015-12-21 05:00:46 -0600

Seen: 292 times

Last updated: Dec 30 '15