1.1 Model Schema

The Honeybee Model schema is a detailed means of describing building geometry in 3D space. It is designed to be extensible such that properties for various simulation engines can be assigned to this geometry. Schemas have been developed to extend the core Honeybee Model for EnergyPlus/OpenStudio as well as Radiance. This section will focus on only describing the core Model schema in the absence of any extensions.

The five geometry objects

Honeybee Models are composed of 5 geometry objects all of which represent planar geometry. In order of most coarse/abstract to most fine/detailed, these objects are

• Room
• Face
• Aperture
• Door
• Shade

Some of these objects can be assigned to others in parent/child object relationships as follows:

The coarsest object in the Honeybee Model schema is the Room, which represents a single closed volume and maps to a zone within energy simulation workflows. Rooms are composed of planar Faces, representing walls, roofs, and floors. Faces can be assigned Apertures, which typically represent windows but can also represent light tubes, daylight domes or any opening that admits light into a building. Faces can also be assigned Doors, which can be opaque or transparent. Lastly, Shades can be assigned to any of the other 4 objects: Rooms, Faces, Apertures, Doors. When they are assigned to Apertures, Shades can represent window sills, mullions, light shelves, louvers, etc. When they are assigned to Doors, they can represent entryway canopies or they can be used to account for the thickness of walls in doorways, When they are assigned to Faces, they can represent balconies and overhangs. When assigned to Rooms, they can represent furniture, interior partitions, etc.

Using geometry objects in a Model

All 5 of these objects can be added to a Honeybee Model object each under a respective key as follows:

The use of the term "orphaned" denotes objects that lack a parent object. For example, an Face under the orphaned_faces key lacks a parent Room. All 5 of these keys are optional but note that you cannot have a simulate-able energy model without rooms (Radiance models are not governed by this restriction). Also note that the only keys that are relevant for energy modeling are rooms and orphaned_shades.

While some models that do not require the parent/child hierarchy can be set up fairly flat, there are a number of advantages to making use of the hierarchy like so: And assigning Shades to the objects they are shading like so:

Using nested object hierarchy

Some advantages of the hierarchical nested schema are that:

• Adding/removing Rooms or Faces from the schema is much easier in that you can simply delete or add a Room and all objects nested underneath it are also deleted/added.
• For large models, it's often advantageous to visualize only a portion of the model and this is faster/easier when objects are nested. For example, if you only want to load a single story of a building, you just get the list of Room names in that story and load all of the geometry objects that are nested under each of the Rooms (no need to lookup Faces, Apertures or other objects in a different part of the schema or interact with the geometry you don’t care about).
• Many of the Honeybee extensions that add properties for simulation engines make use of the fact that some objects are assigned to a parent in order to add capabilities to those objects. For example, Shades assigned to Apertures in Radiance 3-phase simulations can be used to develop shade controls on an aperture-by-aperture basis. Similarly, such simulations make use of the fact that Rooms are closed volumes to run ray tracing calculations of the interior of each Room independently of others.

While hierarchy has advantages, there are limitations and adhering strictly to the object hierarchy can often be an unnecessary formality for many simple studies (like shadow studies) and so the flatter structure with the "orphaned" keys can be used. It is also because of the limitations of hierarchy that Rooms are not the child object of any other object in the Honeybee schema (like Stories or Buildings). Having Rooms as the coarsest object allows for the grouping / editing of Rooms as users see fit, whether this is by story, by orientation of windows, by program, etc. In other words, the flexibility of being able to group Rooms into custom arrays for filtering/editing can often outweigh the benefit of a dedicated object that is meant to take Rooms as children. However, if stories or buildings are needed, these objects are supported in the Dragonfly schema.