This primer provides an overview of the core Honeybee components for Grasshopper.

Note that these docs are only for the core components that are shared across all Honeybee extensions and simulation engines. These shared components include those that build honeybee models from raw geometry, visualize their properties, and serialize them into various file formats. For all attributes and simulation capabilities that are specific to a given simulation engine, please see the docs for those particular extensions.

Here are the docs for the most common honeybee-grasshopper plugin extensions:

• honeybee-grasshopper-radiance

Installation

See the for the installation instructions for the entire Ladybug Tools Grasshopper plugin (including honeybee-grasshopper-core).

Resources

Post your questions to and see the repository for source code.

Please if you find any mistakes in grammar or spelling in this primer and we will gladly fix them.

-

Provides a list of preset values to choose from

- [source code]

Take a list of Honeybee Rooms closed breps (polysurfaces) and split their Faces to ensure that there are matching coplanar faces between them.

This matching between Room faces is required in order to contruct a correct multi-room energy model since conductive heat flow won't occur correctly across interior faces when their surface areas do not match.

Inputs

• rooms [Required]

A list of Honeybee Rooms or closed Rhino breps (polysurfaces) that do not have matching adjacent Faces.

• cpu_count

An integer to set the number of CPUs used in the execution of the intersection calculation. If unspecified, it will automatically default to one less than the number of CPUs currently available on the machine or 1 if only one processor is available.

• run [Required]

Set to True to run the component.

Outputs

• int_rooms

The same input Rooms or closed breps that have had their component faces split by adjacent geometries to have matching surfaces.

- [source code]

Mirror any Honeybee geometry object or a Model across a plane.

Inputs

• hb_objs [Required]

  Any Honeybee geometry object (eg. Room, Face, Aperture, Door or Shade) to be mirrored across a plane. This can also be a Honeybee Model object to be mirrored.

• plane [Required]

  A Plane across which the object will be mirrored.

• prefix

  Optional text string that will be inserted at the start of the identifiers and display names of all transformed objects, their child objects, and their adjacent Surface boundary condition objects. This is particularly useful in workflows where you duplicate and edit a starting object and then want to combine it with the original object into one Model (like making a model of repeated rooms) since all objects within a Model must have unique identifiers. It is recommended that this prefix be short to avoid maxing out the 100 allowable characters for honeybee identifiers. If None, no prefix will be added to the input objects and all identifiers and display names will remain the same. Default: None.

Outputs

• hb_objs

  The input _hb_objs that has been mirrored across the input plane.

- [source code]

Deconstruct any Honeybee geometry object into all of its constituent Honeybee objects.

This is useful for editing auto-generated child objects separately from their parent. For example, if you want to move all of the overhangs that were auto-generated for a Room downward in order to turn them into light shelves, this component can give you all of such shades. Then you can move the shades and assign them back to the original shade-less Room object.

Inputs

• hb_obj [Required]

  A Honeybee Room, Face, Aperture, Door or Shade to be deconstructed into its constituent objects. Note that, Doors and Shades do not have sub-objects assigned to them and the original object will be output.

Outputs

• faces

  All of the Face objects that make up the input _hb_obj. This includes Faces that make up input Rooms as well as any input orphaned Faces.

• apertures

  All of the Aperture objects that make up the input _hb_obj. This includes any Apertures assigned to input Rooms or Faces as well as any input orphaned Apertures.

- [source code]

Specify settings for the run of a recipe, including the number of workers/CPUs, the project folder, and other settings.

Inputs

• folder

Path to a project folder in which the recipe will be executed. If None, the default project folder for the Recipe will be used.

• workers

An integer to set the number of CPUs used in the execution of the recipe. This number should not exceed the number of CPUs on the machine and should be lower if other tasks are running while the simulation is running. If unspecified, it will automatically default to one less than the number of CPUs currently available on the machine. (Default: None)

• reload_old

A boolean to indicate whether existing results for a given model and recipe should be reloaded (if they are found) instead of re-running the entire recipe from the beginning. If False or None, any existing results will be overwritten by the new simulation.

• debug_folder

An optional path to a debug folder. If debug folder is provided, all the steps of the simulation will be executed inside the debug folder which can be used for further inspection.

Outputs

• settings

Recipe settings that can be plugged into any recipe component to specify how the simulation should be run.

- [source code]

Change the display name and identifier of this object and all child objects by inserting a prefix.

This is particularly useful in workflows where you duplicate and edit a starting object and then want to combine it with the original object into one Model (like making a model of repeated rooms) since all objects within a Model must have unique identifiers.

Inputs

• hb_objs [Required]

  A Honeybee Room, Face, Shade, Aperture, or Door to which a prefix should be added to its name.

• prefix [Required]

  Text that will be inserted at the start of this object's (and child objects') identifier and display_name. This will also be added to any Surface boundary conditions of Faces, Apertures, or Doors. It is recommended that this prefix be short to avoid maxing out the 100 allowable characters for honeybee identifiers. This can also be a list of prefixes that correspond to the input _hb_objs

Outputs

• hb_objs

  The input Honeybee objects with a prefix added to their display names and identifiers.

- [source code]

Add extruded border Shades to all the outdoor Apertures of an input Room, Face or Aperture.

This is particularly useful for accounting for the depths of walls/roofs in Radiance simulations or in the solar distribution calculation of EnergyPlus.

Inputs

• hb_objs [Required]

  A list of honeybee Rooms, Faces, or Apertures to which extruded border shades will be added.

• depth [Required]

  A number for the extrusion depth. If an array of values are input here, different depths will be assigned based on cardinal direction, starting with north and moving clockwise.

Outputs

• report

  Reports, errors, warnings, etc.

• hb_objs

  The input Honeybee Face or Room or Aperture with extruded border shades added to it.

- [source code]

Deconstruct a Honeybee Model object into all of its constituent Honeybee objects.

Inputs

• model [Required]

  A Honeybee Model to be deconstructed into into its constituent objects (Rooms, Faces, Apertures, Doors Shades).

Outputs

• rooms

  All of the Room objects contained within the input Model.

• faces

  All of the orphaned Face objects within the input Model. This only oncludes parent-less Faces and does not include any Faces that belong to a Room.

- [source code]

Create Honeybee Door

Inputs

• geo [Required]

  Rhino Brep or Mesh geometry.

• name

  A name for the Door. If the name is not provided a random name will be assigned.

• glass

  Boolean to note whether the Door is transparent. Default: False.

• ep_constr

  Optional text for the Door's energy construction to be looked up in the construction library. This can also be a custom construction object. If no energy construction is input here, a default will be assigned based on the properties of the parent face that the Door is assigned to (ie. whether the Face is a RoofCeiling, whether it has a Surface boundary condition, etc.)

• rad_mod

  Optional text for the Door's radiance modifier to be looked up in the modifier library. This can also be a custom modifier object. If no radiance modifier is input here, a default will be assigned based on the properties of the parent face that the Door is assigned to (ie. whether the Face is a RoofCeiling, whether it has a Surface boundary condition, etc.)

Outputs

• report

  Reports, errors, warnings, etc.

• doors

  Honeybee doors. These can be used directly in radiance simulations or can be added to a Honeybee face for energy simulation.

- [source code]

Set text for the zone identifier for honeybee Rooms.

Rooms sharing the same zone identifier are considered part of the same zone in a Model. If a zone identifier has not been specified for a given Room, it will be the same as the Room identifier.

Inputs

• rooms [Required]

Honeybee Rooms to which the input _zone identifier should be assigned.

• zone [Required]

Text for the zone identifier to which the rooms belong.

Outputs

• report

...

• rooms

The input Rooms with their zones set.

-

Solve adjacencies between a series of honeybee Rooms.

Note that rooms must have matching faces in order for them to be discovered as adjacent.

Inputs

-

Add apertures to a Honeybee Face or Room given a ratio of aperture area to face area.

Note that this component will only add Apertures to Faces that are Walls and have an Outdoors boundary condition.

Inputs

-

Add a Honeybee Shades to an Aperture, Door, Face or Room.

Inputs

-

Add skylight apertures to a Honeybee Face or Room given a ratio of aperture area to face area.

Note that this component will only add Apertures to Faces that are Roofs and have an Outdoors boundary condition.

Inputs

-

THIS COMPONENT IS INTENDED FOR ADVANCED USERS WHO UNDERSTAND THAT IDENTIFERS SHOULD BE UNIQUE AND THAT, TO SET THEM OTHERWISE CAN HAVE UNINTENDED CONSEQUENCES.

Change the identifier of any Honeybee object.

Note that this component only changes the identifer of the input _hb_obj and none of the identifiers of the child objects.

-

Visualize room geometry in the Rhino scene organized by boundary condition.

Inputs

-

Serialize any honeybee object to a JSON text string. You can use "HB String to Object" component to load the objects from the file back.

Honeybee objects include any honeybee energy Material, Construction, ConstructionSet, Schedule, Load, ProgramType, or Simulation object.

-

Set text for the story identifier for honeybee Rooms.

Rooms sharing the same story identifier are considered part of the same story in a Model.

Inputs

-

Planarize Rhino breps in a manner that allows control over the meshing process.

The resulting planar breps will be solid if the input brep is solid and any planar faces of the brep will remain unchanged except for the polygonization of curved edges.

-

Preview any Honeybee geometry object within the Rhino scene, including all sub-faces and assigned shades.

Inputs

-

Set the boundary conditions of Rooms to be Ground vs. Outdoors using a surface or polysurface that represents the ground.

Room faces that are coplanar with the ground surface or have a center below it will get a Ground boundary condition. Existing Faces with a Surface/Adiabatic condition, AirBoundary type, or assigned Apertures/Doors will be unaffected.

Note that this component will not intersect the Faces with the ground surface and this is intersection should be done prior to the creation of the Honeybee Rooms.

-

Launch a browser window that can be used to visualize the execution and logs of any currently-running recipe.

Note that this component will only open the recipe visualizer in the default browser and the page must be refreshed after starting a recipe run in order for the latest recipe execution status to be visible.

Also note that the "Let [RECIPE NAME] Fly" task contains all of the information about a given recipe run. Selecting "View Graph" for this task and then un-checking "Hide Done" will allow one to see the full progress of the recipe.

-

Provides a list of preset values to choose from

-

Quickly preview any Honeybee geometry object within the Rhino scene.

Sub-faces and assigned shades will not be included in the output, allowing for a faster preview of large lists of objects but without the ability to check the assignment of child objects.

-

Rotate any Honeybee geometry object or a Model by an angle.

Inputs

-

Automatically group rooms with similar properties and use the groups to assign zones.

Relevant properties that are used to group Room2Ds into zones include story, orientation, and (optionally) energy programs.

Rooms that share the same zone have a common thermostat in energy simulation. This can often significnatly reduce simulation time without greatly impacting energy use results.

-

Separate and group Honeybee Faces, Apertures, Doors and Shades by any attribute that the objects possess.

This can be used to group faces by construction, modifier, etc.

Inputs

-

Generate lists of facadce properties ordanized by the four primary cardinal directions.

Such properties can be glazing ratios, glazing heigths, sill heights, horizontal/ vertical glazing splits for the "HB Apertures by Ratio" component. Or they could be shade depths, angles, etc. for the "HB Louver Shades" component.

-

Lablel Honeybee rooms with their attributes in the Rhino scene.

This can be used as a means to check that correct properties are assigned to different Rooms.

Inputs

-

Get aligned points and vectors to preview the normal direction of any Honeybee geometry object the Rhino scene, including all sub-faces and assigned shades.

Inputs

-

Create Honeybee Shade.

Inputs

• Deconstruct Model

• Model

- [source code]

Create Honeybee Rooms from solids (closed Rhino polysurfaces).

Note that each Room is mapped to a single zone in EnergyPlus/OpenStudio and should always be a closed volume to ensure correct volumetric calculations and avoid light leaks in Radiance simulations.

Inputs

• geo [Required]

A list of closed Rhino polysurfaces (aka.breps) to be converted into honeybee Rooms. This list can also include closed meshes that represent the rooms.

• name

Text to set the base name for the Room, which will also be incorporated into unique Room identifier. If the name is not provided, a random name will be assigned.

• mod_set

Text for the modifier set of the Rooms, which is used to assign all default radiance modifiers needed to create a radiance model. Text should refer to a ModifierSet within the library) such as that output from the "HB List Modifier Sets" component. This can also be a custom ModifierSet object. If nothing is input here, the Room will have a generic construction set that is not sensitive to the Room's climate or building energy code.

• constr_set

Text for the construction set of the Rooms, which is used to assign all default energy constructions needed to create an energy model. Text should refer to a ConstructionSet within the library such as that output from the "HB List Construction Sets" component. This can also be a custom ConstructionSet object. If nothing is input here, the Rooms will have a generic construction set that is not sensitive to the Rooms's climate or building energy code.

• program

Text for the program of the Rooms (to be looked up in the ProgramType library) such as that output from the "HB List Programs" component. This can also be a custom ProgramType object. If no program is input here, the Rooms will have a generic office program. Note that ProgramTypes effectively map to OpenStudio space types upon export to OpenStudio.

• conditioned

Boolean to note whether the Rooms have heating and cooling systems.

• roof_angle

A number between 0 and 90 to set the angle from the horizontal plane below which faces will be considered roofs or floors instead of walls. 90 indicates that all vertical faces are roofs and 0 indicates that all horizontal faces are walls. The default value of 60 degrees is the recommended value given by the ASHRAE 90.1 standard. (Default: 60).

Outputs

• report

Reports, errors, warnings, etc.

• rooms

Honeybee rooms. These can be used directly in energy and radiance simulations.

- [source code]

Separate the faces/sub-faces of honeybee Rooms, Faces, Apertures, Doors, or Shades by object and face type.

Inputs

• hb_objs [Required]

  Honeybee Rooms, Faces, Apertures, Doors and/or Shades which will be separated based on object and face type. This can also be an entire honeybee Model.

Outputs

• walls

  The Walls with an Outdoors or Ground boundary condition.

• interior_walls

  The Walls with a Surface or Adiabatic boundary condition.

- [source code]

Create Honeybee Face

Inputs

• geo [Required]

  Rhino Brep or Mesh geometry.

• name

  Text to set the name for the Face and to be incorporated into unique Face identifier. If the name is not provided, a random name will be assigned.

• type

  Text for the face type. The face type will be used to set the material and construction for the surface if they are not assigned through the inputs below. The default is automatically set based on the normal direction of the Face (up being RoofCeiling, down being Floor and vertically-oriented being Wall). Choose from the following:

  • Wall

• bc

  Text for the boundary condition of the face. The boundary condition is also used to assign default materials and constructions as well as the nature of heat excahnge across the face in energy simulation. Default is Outdoors unless all vertices of the geometry lie below the below the XY plane, in which case it will be set to Ground. Choose from the following:

  • Outdoors

• ep_constr

  Optional text for the Face's energy construction to be looked up in the construction library. This can also be a custom OpaqueConstruction object. If no energy construction is input here, the face type and boundary condition will be used to assign a default.

• rad_mod

  Optional text for the Face's radiance modifier to be looked up in the modifier library. This can also be a custom modifier object. If no radiance modifier is input here, the face type and boundary condition will be used to assign a default.

Outputs

• report

  Reports, errors, warnings, etc.

• faces

  Honeybee surface. Use this surface directly for daylight simulation or to create a Honeybee zone for Energy analysis.

- [source code]

Separate and group honeybee rooms with the same average floor height.

Inputs

• rooms [Required]

  A list of honeybee Rooms or honeybee Models to be separated by floor height.

• min_diff

  An optional float value to denote the minimum difference in floor heights that is considered meaningful. This can be used to ensure rooms like those representing stair landings are grouped with floors. If None, any difference in floor heights greater than the Rhino model tolerance will be considered meaningful.

Outputs

• flr_hgts

  A list of floor heights with one floor height for each branch of the output rooms.

• rooms

  A data tree of honeybee rooms with each branch of the tree representing a different floor height.

- [source code]

Create a Honeybee Model, which can be sent for simulation.

Inputs

• rooms

A list of honeybee Rooms to be added to the Model. Note that at least one Room is necessary to make a simulate-able energy model.

• faces

A list of honeybee Faces to be added to the Model. Note that faces without a parent Room are not allowed for energy models.

• shades

A list of honeybee Shades or ShadeMeshes to be added to the Model.

• apertures

A list of honeybee Apertures to be added to the Model. Note that apertures without a parent Face are not allowed for energy models.

• doors

A list of honeybee Doors to be added to the Model. Note that doors without a parent Face are not allowed for energy models.

• name

Text to be used for the Model name and to be incorporated into a unique model identifier. If no name is provided, it will be "unnamed" and a unique model identifier will be auto-generated.

Outputs

• report

Reports, errors, warnings, etc.

• model

A Honeybee Model object possessing all of the input geometry objects.

- [source code]

Visualize room geometry in the Rhino scene organized by object and face type.

Inputs

• hb_objs [Required]

  A Honeybee Model, Room, Face, Aperture, Door or Shade to be previewed in the Rhino scene based on type.

Outputs

• walls

  Rhino geometry for the Walls with an Outdoors or Ground boundary condition.

• interior_walls

  Rhino geometry for the Walls with a Surface or Adiabatic boundary condition.

- [source code]

Color Honeybee rooms in the Rhino scene using their attributes.

This can be used as a means to check that correct properties are assigned to different Rooms.

Inputs

• rooms_model [Required]

An array of honeybee Rooms or honeybee Models to be colored with their attributes in the Rhino scene.

• attribute [Required]

Text for the name of the Room attribute with which the Rooms should be labeled. The Honeybee "Room Attributes" component lists all of the core attributes of the room. Also, each Honeybee extension (ie. Radiance, Energy) includes its own component that lists the Room attributes of that extension.

• legend_par

An optional LegendParameter object to change the display of the colored rooms (Default: None).

Outputs

• mesh

Meshes of the room floors colored according to their attributes.

• legend

Geometry representing the legend for colored meshes.

• wire_frame

A list of lines representing the outlines of the rooms.

• values

A list of values that align with the input _rooms noting the attribute assigned to each room.

• colors

A list of colors that align with the input Rooms, noting the color of each Room in the Rhino scene. This can be used in conjunction with the native Grasshopper "Custom Preview" component and other honeybee visualization components (like "HB Visulaize Quick") to create custom visualizations in the Rhino scene.

• vis_set

An object containing VisualizationSet arguments for drawing a detailed version of the ColorRoom in the Rhino scene. This can be connected to the "LB Preview Visualization Set" component to display this version of the visualization in Rhino.

- [source code]

Dump any honeybee object to a JSON file. You can use "HB Load Objects" component to load the objects from the file back into Grasshopper.

Honeybee objects include any honeybee energy Material, Construction, ConstructionSet, Schedule, Load, ProgramType, or Simulation object.

Inputs

• hb_objs [Required]

A list of Honeybee objects to be written to a file.

• name

A name for the file to which the honeybee objects will be written. (Default: 'unnamed').

• folder

An optional directory into which the honeybee objects will be written. The default is set to the default simulation folder.

• indent

An optional positive integer to set the indentation used in the resulting JSON file.

• abridged

Set to "True" to serialize the object in its abridged form. Abridged objects cannot be reserialized back to honeybee objects on their own but they are used throughout honeybee to minimize file size and unnecessary duplication.

• dump [Required]

Set to "True" to save the honeybee objects to file.

Outputs

• report

Errors, warnings, etc.

• hb_file

The location of the file where the honeybee JSON is saved.

- [source code]

Color Honeybee Faces, Apertures, Doors and Shades in the Rhino scene using their attributes.

This can be used as a means to check that correct properties are assigned to different faces.

Inputs

• hb_objs [Required]

An array of honeybee Rooms, Faces, Apertures, Doors or Shades to be colored with their attributes in the Rhino scene. This can also be an entire Model to be colored.

• attribute [Required]

Text for the name of the attribute with which the faces or sub-faces should be labeled. The Honeybee "Face Attributes" component lists all of the core attributes of the room. Also, each Honeybee extension (ie. Radiance, Energy) includes its own component that lists the face and sub-face attributes of that extension.

• legend_par

An optional LegendParameter object to change the display of the colored faces and sub-faces (Default: None).

Outputs

• mesh

Meshes of the faces and sub-faces colored according to their attributes.

• legend

Geometry representing the legend for colored meshes.

• wire_frame

A list of lines representing the outlines of the _hb_objs.

• values

A list of values noting the attribute assigned to each face/sub-face.

• colors

A list of colors noting the color of each face/sub-face in the Rhino scene. This can be used in conjunction with the native Grasshopper "Custom Preview" component to create custom visualizations in the Rhino scene.

• vis_set

An object containing VisualizationSet arguments for drawing a detailed version of the ColorRoom in the Rhino scene. This can be connected to the "LB Preview Visualization Set" component to display this version of the visualization in Rhino.

- [source code]

Add a Honeybee Aperture or Door to a parent Face or Room.

Inputs

• hb_obj [Required]

A Honeybee Face or a Room to which the _sub_faces should be added. This can also be an entire Honeybee Model in which case Apertures will be added to all FAces of the Model (including both Room Faces and orphaned Faces).

• sub_faces [Required]

A list of Honeybee Apertures and/or Doors that will be added to the input _hb_obj.

• project_dist

An optional number to be used to project the Aperture/Door geometry onto parent Faces. If specified, then Apertures within this distance of the parent Face will be projected and added. Otherwise, Apertures/Doors will only be added if they are coplanar and fully bounded by a parent Face.

Outputs

• report

Reports, errors, warnings, etc.

• hb_obj

The input Honeybee Face or a Room with the input _sub_faces added to it.

• unmatched

A list of any Apertures or Doors that could not be matched and assigned to a parent Face.

- [source code]

Load any honeybee object from a compressed .pkl or .hbpkl file.

Honeybee objects include any Model, Room, Face, Aperture, Door, Shade, or boundary condition object.

It also includes any honeybee energy Material, Construction, ConstructionSet, Schedule, Load, ProgramType, or Simulation object.

Inputs

• hb_file [Required]

  A file path to a .pkl or .hbpkl from which objects will be loaded back into Grasshopper.

• load [Required]

  Set to "True" to load the objects from the _hb_file.

Outputs

• report

  Reports, errors, warnings, etc.

• hb_objs

  A list of honeybee objects that have been re-serialized from the input file.

- [source code]

Load any honeybee object from a honeybee JSON file

Honeybee objects include any Model, Room, Face, Aperture, Door, Shade, or boundary condition object.

It also includes any honeybee energy Material, Construction, ConstructionSet, Schedule, Load, ProgramType, or Simulation object.

Inputs

• hb_file [Required]

  A file path to a honeybee JSON from which objects will be loaded back into Grasshopper. The objects in the file must be non-abridged in order to be loaded back correctly.

• load [Required]

  Set to "True" to load the objects from the _hb_file.

Outputs

• report

  Reports, errors, warnings, etc.

• hb_objs

  A list of honeybee objects that have been re-serialized from the input file.

- [source code]

Separate the faces/sub-faces of honeybee Rooms, Faces, Apertures, Doors or Shades by boundary condition.

Inputs

• hb_objs [Required]

  Honeybee Rooms, Faces, Apertures, Doors and/or Shades which will be separated based on boundary condition. This can also be an entire honeybee Model.

Outputs

• outdoors

  The objects with an Outdoors boundary condition.

• surface

  The objects with a Surface (interior) boundary condition.

- [source code]

Move any Honeybee geometry object or a Model object along a vector.

Inputs

• hb_objs [Required]

  Any Honeybee geometry object (eg. Room, Face, Aperture, Door or Shade) to be moved along the input vector. This can also be a Honeybee Model object to be moved.

• vector [Required]

  A Vector3D with the direction and distance to move the _hb_objs.

• prefix

  Optional text string that will be inserted at the start of the identifiers and display names of all transformed objects, their child objects, and their adjacent Surface boundary condition objects. This is particularly useful in workflows where you duplicate and edit a starting object and then want to combine it with the original object into one Model (like making a model of repeated rooms) since all objects within a Model must have unique identifiers. It is recommended that this prefix be short to avoid maxing out the 100 allowable characters for honeybee identifiers. If None, no prefix will be added to the input objects and all identifiers and display names will remain the same. Default: None.

Outputs

• hb_objs

  The input _hb_objs that has been moved along the input vector.

- [source code]

Simplify the Apertures assigned to Honeybee Rooms or Faces to be as few as possible while still maintaining approximately the same overall Aperture area.

By default, this component will only simplify Apertures in convex Faces by reducing them to a ratio represented with one or two clean Apertures. For models without many concave Faces, this process usually produces a fast-simulating result that matches the original window area exactly. However, this operation will also change the placement of Apertures within a Face, which may make it unsuitable for modeling the impact of Shades on Apertures or for evaluating daylight.

For cases with concave Faces (which is typical for Roofs/Skylights) or when it is desirable to keep Apertures in the same location within the parent Face, the Apertures can be simplified by specifying a merge_dist_, which will join together Apertures in close proximity to one another rather than reducing them to a ratio.

Inputs

• hb_objs [Required]

A list of honeybee Rooms or Faces to which Apertures will be simplified. This can also be an entire honeybee Model for which all Rooms will have Apertures simplified.

• merge_dist

Distance between Apertures and/or Doors at which point they will be merged into a single Aperture. When unspecified, only Apertures within convex faces will be reduced to a ratio. This will match the original Aperture area exactly but it will change the placement of Apertures within the Face, which can make it unsuitable for modeling the impact of Shades on Apertures. When a value is specified here, concave Faces will be addressed and Apertures will remain where they are in the parent Face. The overall Aperture area may be a little larger thanks to merging across gaps that are less than or equal to the value specified but the result will be suitable for evaluating the impact of Shades or simulating daylight.

• del_interior

Boolean to note whether the simplification process should remove all interior Apertures with a Surface boundary condition (True) or an attempt will be made to reset adjacencies after Apertures have been simplified/rebuilt (False). (Default: False).

• ignore_skylights

Boolean to note whether the simplification process should ignore all skylights and leave them as they are. (Default: False).

• ignore_windows

Boolean to note whether the simplification process should ignore all windows and leave them as they are. (Default: False).

Outputs

• report

Reports, errors, warnings, etc.

• hb_objs

The input Honeybee Face, Room or Model with Apertures simplified.

- [source code]

Check the versions of the engines that are being used by the honeybee plugin. This is useful for verifying that everything has been installed correctly and that the versions of the engines are as expected.

Inputs

Outputs

• lbt_gh

The version of Ladybug Tools for Grasshopper that is installed.

• python

The version of Python used for Ladybug Tools CLI calls.

• radiance

The version of Radiance used by Ladybug Tools (will be None if it is not installed).

• openstudio

The version of OpenStudio used by Ladybug Tools (will be None if it is not installed).

• energyplus

The version of EnergyPlus used by Ladybug Tools (will be None if it is not installed).

- [source code]

Serialize any honeybee JSON text string back to a honeybee object.

Honeybee objects include any Model, Room, Face, Aperture, Door, Shade, or boundary condition object.

It also includes any honeybee energy Material, Construction, ConstructionSet, Schedule, Load, ProgramType, or Simulation object.

Inputs

• hb_str [Required]

  A text string that completely describes the honeybee object.

Outputs

• hb_obj

  A Honeybee object serialized from the input string.

- [source code]

Dump any honeybee object to a compressed .pkl file. You can use "HB Load Compressed Objects" component to load the objects from the file back into Grasshopper.

Honeybee objects include any Model, Room, Face, Aperture, Door, Shade, or boundary condition object

It also includes any honeybee energy Material, Construction, ConstructionSet, Schedule, Load, ProgramType, or Simulation object.

Inputs

• hb_objs [Required]

  A Honeybee object (or list of Honeybee objects) to be written to a file.

• name

  A name for the file to which the honeybee objects will be written. (Default: 'unnamed').

Outputs

• report

  Errors, warnings, etc.

• hb_file

  The location of the file where the honeybee .pkl file is saved.

- [source code]

Check the local configuration of the engines and data sets used by the honeybee plugin. This is useful for verifying that everything has been installed correctly and that the engines are configured as expected.

Inputs

Outputs

• python_exe

  The path to the Python executable to be used for Ladybug Tools CLI calls.

• py_lib_install

  The path to where the Ladybug Tools Python packages are installed.

- [source code]

Create Honeybee Aperture

Inputs

• geo [Required]

  Rhino Brep or Mesh geometry.

• name

  Text to set the name for the Aperture and to be incorporated into unique Aperture identifier. If the name is not provided, a random name will be assigned.

• operable

  Boolean to note whether the Aperture can be opened for ventilation.

• ep_constr

  Optional text for the Aperture's energy construction to be looked up in the construction library. This can also be a custom WindowConstruction object. If no energy construction is input here, a default will be assigned based on the properties of the parent face that the Aperture is assigned to (ie. whether the Face is a RoofCeiling, whether it has a Surface boundary condition, etc.)

• rad_mod

  Optional text for the Aperture's radiance modifier to be looked up in the modifier library. This can also be a custom modifier object. If no radiance modifier is input here, a default will be assigned based on the properties of the parent face that the Aperture is assigned to (ie. whether the Face is a RoofCeiling, whether it has a Surface boundary condition, etc.)

Outputs

• report

  Reports, errors, warnings, etc.

• apertures

  Honeybee apertures. These can be used directly in radiance simulations or can be added to a Honeybee face for energy simulation.

- [source code]

Separate and group honeybee rooms with the same average orientation of walls with an Outdoors boundary condition.

Inputs

• rooms [Required]

  A list of honeybee honeybee Rooms or honeybee Models to be separated by orientation.

• n_groups

  An optional positive integer to set the number of orientation groups to use. For example, setting this to 4 will result in rooms being grouped by four orientations (North, East, South, West). If None, the maximum number of unique groups will be used.

• north

  A number between 0 and 360 to set the clockwise north direction in degrees. This can also be a vector to set the North. Default is 0.

Outputs

• orientations

  A list of numbers between 0 and 360 with one orientation for each branch of the output perimrooms. This will be a list of angle ranges if a value is input for n_groups.

• perim_rooms

  A data tree of honeybee rooms with each branch of the tree representing a different orientation.

-

Lablel Honeybee faces and sub-faces with their attributes in the Rhino scene.

This can be used as a means to check that correct properties are assigned to different faces and sub-faces.

Inputs

-

Upgrade a Model HBJSON file to the currently installed version of the schema.

This component can also upgrade to a specific version of the schema but it cannot downgrade the schema version or change the version of any honeybee object other than a Model.

A full list of honeybee-schema versions can be found on the honeybee-schema GitHub:

-

Get a validation report that contains a summary of all issues with the Model.

This includes basic properties like adjacency checks and all geometry checks. Furthermore, all extension attributes for Energy and Radiance will be checked to ensure that the model can be simulated correctly in these engines.

-

Add apertures to a Honeybee Face or Room given a width and a height of windows that repeat across the walls at a specific horizontal separation between window centerlines.

Note that this component will only add Apertures to Faces that are Walls, have an Outdoors boundary condition, and have at least a portion of the Face that is clearly rectangular.

Inputs

-

Set the properties of room Faces using (a) guide surface(s) or polysurface(s).

Faces that are touching and coplanar with the guide surface will get their properties changed to match the inputs.

This is useful for colelctively setting the properties of spatially aligned Faces, like setting Faces along a given stretch of a parti wall to be adiabatic.

-

Dump a Honyebee Model to a gbXML file.

The gbXML format is a common open standard used to transfer energy model geometry and (some) energy simulation properties from one simulation environment to another.

The forward translators within the OpenStudio SDK are used to export all Honeybee model geometry and properties.

-

Scale any Honeybee geometry object or a Model by a factor.

Inputs

-

Set the apertures of room Faces using (a) guide surface(s) or polysurface(s).

Faces that are touching and coplanar with the guide surface will get their aperters changed according to the input properties.

Inputs

-

Quickly preview any Honeybee geometry object as a wire frame within the Rhino scene, including all sub-faces and assigned shades.

Inputs

-

Get geometry properties of honeybee Rooms or a honeybee Model.

Inputs

-

Offset the edges of all Apertures of a Honeybee Room or Face by a certain distance.

This is useful for translating between interfaces that expect the window frame to be included within or excluded from the geometry of the Aperture. For example, EnergyPlus expects Aperture geometry to be for only the glass portion of the window while IES-VE expects the Aperture geometry to include the frame.

Note that this component also has usefulness to simply repair cases where Apertures extend pas their parent Face or overlap with one another. In this situation, the offset input can be set to zero and the repair_ boolean set to True to only run the repair operation.

- [source code]

Get the edges of a Model's envelope grouped based on the objects they adjoin.

The edges returned by this component will only exist along the exterior envelope of the Model's rooms as defined by the contiguous volume across all interior adjacencies. In this way, edges that adjoin two honeybee rooms will only be represented once in the list (and not twice for the two rooms).

The lengths of the resulting edges are useful for evaluating thermal bridges across the model.

Inputs

• model [Required]

A honeybee Model with rooms for which adjacencies have been solved.

• ex_coplanar

Boolean to note whether edges falling between two coplanar Faces in the building envelope should be included in the result (False) or excluded from it (True). (Default: True).

• mullion_thick

The maximum difference that apertures or doors can be from one another for the edges to be considered a mullion rather than a frame. If None, all edges of apertures and doors will be considered frames rather than mullions.

Outputs

• aperture_frames

A list of line segments for where exterior apertures meet their parent exterior wall or roof.

• aperture_mullions

A list of line segments for where exterior apertures meet one another.

• door_frames

A list of line segments for where exterior doors meet their parent exterior wall or roof.

• door_mullions

A list of line segments for where exterior doors meet one another.

• roofs_to_walls

A list of line segments where roofs meet exterior walls (or floors). Note that both the roof Face and the wall/floor Face must be next to one another in the model's outer envelope and have outdoor boundary conditions for the edge to show up in this list.

• slabs_to_walls

A list of line segments where ground floor slabs meet exterior walls or roofs. Note that the floor Face must have a ground boundary condition and the wall or roof Face must have an outdoor boundary condition for the edge between the two Faces to show up in this list.

• exp_floors_to_walls

A list of line segments where exposed floors meet exterior walls. Note that both the wall Face and the floor Face must be next to one another in the model's outer envelope and have outdoor boundary conditions for the edge to show up in this list.

• ext_walls_to_walls

A list of line segments where exterior walls meet one another. Note that both wall Faces must be next to one another in the model's outer envelope and have outdoor boundary conditions for the edge to show up in this list.

• roof_ridges

A list of line segments where exterior roofs meet one another. Note that both roof Faces must be next to one another in the model's outer envelope and have outdoor boundary conditions for the edge to show up in this list.

• exp_floors_to_floors

A list of line segments where exposed floors meet one another. Note that both floor Faces must be next to one another in the model's outer envelope and have outdoor boundary conditions for the edge to show up in this list.

• underground

A list of line segments where underground Faces meet one another. Note that both Faces must be next to one another in the model's outer envelope and have ground boundary conditions for the edge to show up in this list.

-

Change the multiplier of a honeybee Room.

Multipliers are used to speed up the calculation when similar Rooms are repeated more than once. Essentially, a given simulation with the Room is run once and then the result is multiplied by the multiplier. This means that the "repetition" isn't in a particular direction (it's essentially in the exact same location) and this comes with some inaccuracy. However, this error might not be too large if the Rooms are similar enough and it can often be worth it since it can greatly speed up the calculation.

- [source code]

Separate and group honeybee Rooms by any attribute that the room possesses.

This can be used to group rooms by program, whether rooms are conditioned, etc.

Inputs

• rooms [Required]

An array of honeybee Rooms or honeybee Models to be separated and grouped based on their attributes.

• attribute [Required]

Text for the name of the Room attribute with which the Rooms should be labeled. The Honeybee "Room Attributes" component lists all of the core attributes of the room. Also, each Honeybee extension (ie. Radiance, Energy) includes its own component that lists the Room attributes of that extension.

• value

An optional value of the attribute that can be used to filter the output rooms. For example, if the input attribute is "Program" a value for the name of a program can be plugged in here (eg. "2019::LargeOffice::OpenOffice") in order to get only the rooms that have this program assigned.

Outputs

• values

A list of values with one attribute value for each branch of the output rooms.

• rooms

A data tree of honeybee rooms with each branch of the tree representing a different attribute value.

-

Get the straight skeleton and core/perimeter sub-faces for any planar geometry.

This component uses a modified version of the the polyskel package (https://github.com/Botffy/polyskel) by Armin Scipiades (aka. @Bottfy), which is, itself, a Python implementation of the straight skeleton algorithm as described by Felkel and Obdrzalek in their 1998 conference paper Straight skeleton implementation (https://github.com/Botffy/polyskel/blob/master/doc/StraightSkeletonImplementation.pdf).

- [source code]

Load a gbXML, OSM, or IDF file as a Honeybee Model.

The reverse translators within the OpenStudio SDK are used to import all geometry and boundary conditions (including adjacencies) to a Honeybee format.

Note that, while all geometry will be imported, it is possible that not all of the properties assigned to this geometry will be imported, particularly if a certain property is not supported in the OpenStudio SDK. Honeybee will assign defaults for missing properites.

Inputs

• model_file [Required]

A file path to a gbXML, OSM or IDF file from which a Honeybee Model will be loaded.

• reset_props

Set to True to have all energy properties reset to defaults upon import, meaning that only the geometry and boundary conditions are imported from the model file. (Default: False).

• load [Required]

Set to "True" to load the Model from the input file.

Outputs

• report

...

• model

A honeybee Model objects that has been re-serialized from the input file.

-

Create Honeybee Room from Honeybee Faces.

Note that each Room is mapped to a single zone in EnergyPlus/OpenStudio and should always be a closed volume to ensure correct volumetric calculations and avoid light leaks in Radiance simulations.

-

Add louverd Shades, overhangs or fins to all the outdoor Apertures of an input Room, Face or Aperture.

Note that, if a Face or Room is input, Shades will only be added to those Faces that are Walls (not Floors or Roofs).

Inputs