Get Unique Objects
OpenStudio.idd includes details about the unique objects in the OpenStudio. The idd file is accessible here. The unique objects are marked as unique-object.
The following objects are unique:
- Building
- Site
- Facility
- Simulation Control
- Run Period
- Time Step
- Inside Surface Convection Algorithm
- Outside Surface Convection Algorithm
- Heat Balance Algorithm
- Zone Air Heat Balance Algorithm
- Convergence Limits
- Sizing Parameters
- Shadow Calculation
- Year Description
Therefore, to get these unique model objects, the following "get" methods need to be used:
- getBuilding
- getSite
- getFacility
- getSimulationControl
- getRunPeriod
- getTimestep (Note: it is not getTimeStep)
- getInsideSurfaceConvectionAlgorithm.setAlgorithm("TARP")
- getOutsideSurfaceConvectionAlgorithm.setAlgorithm("DOE-2")
- getHeatBalanceAlgorithm
- getZoneAirHeatBalanceAlgorithm.setAlgorithm("AnalyticalSolution")
- getConvergenceLimits
- getSizingParameters
- getShadowCalculation
- getYearDescription
Then, when the user gets the unique model objects, the values for each field can be set. The following example shows how different fields in the OS:Building objects can be set.
# get the building
building=model.getBuilding
# set the model name
building.setName("OpenStudioModel")
# set the north axis of the building
building.setNorthAxis(180.0)
It is important to note that some of the fields for the unique objects are under different objects in E+ and OpenStudio. An example is "Terrain" field. In E+, this field is under the "Building"; however, in the OpenStudio, this field is under "Site" object. Therefore, to set the value, this code needs to be used:
# set the terrain. "City", "Country", "Suburbs", "Ocean", "Urban" are the options
# For detailed information about this field, please visit the E+ I/O Reference
model.getSite.setTerrain("City")
Also, it is important to note that when user gets some of the unique objects, the API automatically provides the minimum number of fields that the object needs. However, for some of the objects this does not happen. The following example illustrates this difference.
-
Example of getBuilding (This method creates all of the necessary fields when the method is used)
-
Example of getConvergenceLimits (This method does not create all of the necessary fields when the method is used)
For the first type of get unique objects, similar to getBuilding, it is easier to guess how to set the fields and what fields are inside of the object. For example, the getBuilding shows that the Terrain is not part of this object. E+ developers usually set the Terrain in the Building, object. For the second type of get unique objects, similar to getConvergenceLimits, the OpenStudio user needs to check the OpenStudio github repository or guess the fields from the E+ idf file. Here is an example to add additional fields to the second type of get unique objects.
# get the convergence limits
convergenceLimits=model.getConvergenceLimits
# set the minimum number of system timestep
convergenceLimits.setMinimumSystemTimestep(2)
This section explains different methods available in the OS:Facility. Facility has a hierarchy that is under the OS:Building object. Facility works as a wrapper around the current external meters for the building or organizing outputs. For example, the following codes show how to add the exterior lights to the model.
# get the facility
facility = model.getFacility
# check if the facility has already exterior lights
if facility.to_ExteriorLightsDefinition.empty?
puts "\nNo exterior light is defined\n"
end
# create exterior light definition
exterior_Lights_Definition = OpenStudio::Model::ExteriorLightsDefinition.new(model)
exterior_Lights_Definition.setName("Exterior Light Level - 1500W")
exterior_Lights_Definition.setDesignLevel(1500)
Year Description is empty by default. When you ask for getYearDescription, this object is created in the OpenStudio model. There are different methods such as:
- makeDate
- setCalendarYear
- dayOfWeek
- dayOfMonth
- dayOfYear
The following example shows how these methods can be used.
require 'openstudio'
model = OpenStudio::Model::Model.new
yearDescription = model.getYearDescription
# This starts from 2009 because OS established in 2009
# It is possible to assign a specific year
puts os_date = year.makeDate(100)
# This is how to set the year. First you need to make a year and then set it.
puts yearDescription.setCalendarYear(2016)
puts year.dayOfWeek
# This provides the day name; it is important to note that
# `os_date.dayOfYear.valueName` and `#puts os_date.dayOfMonth.valueName` are
# `unassigned integer`. So, they do not return any values
puts day_of_week = os_date.dayOfWeek.valueName
puts os_date.dayOfYear
puts os_date.dayOfMonth