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

• honeybee-grasshopper-energy

Installation

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

Resources

Post your questions to Ladybug Tools forum and see the honeybee-grasshopper-core repository for source code.

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

-

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.

• doors

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

• shades

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

-

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.

-

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.

• apertures

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

• doors

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

• shades

  All of the orphaned Shade objects within the input Model. This only oncludes parent-less Shades and does not include any Shades that belong to an Aperture, Face, or Room.

- [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]

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.

Inputs

• brep [Required]

  A list of closed Rhino polysurfaces (aka. breps) to be planarized.

• mesh_par

  Optional Rhino Meshing Parameters to describe how curved faces should be convereted into planar elements. These can be obtained from the native Grasshopper mesh Settings components. If None, Rhino's Default Meshing Parameters will be used, which tend to be very coarse and simple.

Outputs

• report

  Reports, errors, warnings, etc.

• pl_brep

  A planar version of the input _brep.

-

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.

Inputs

• faces [Required]

  A list of honeybee Faces to be joined together into a Room.

• name

  Text to set the name for the Room and to 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 Room, 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 Room, 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 Room will have a generic construction set that is not sensitive to the Room's climate or building energy code.

• program

  Text for the program of the Room (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 Room 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 Room has a heating and cooling system.

Outputs

• report

  Reports, errors, warnings, etc.

• room

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

- [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]

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

• rooms [Required]

  A list of honeybee Rooms for which adjacencies will be solved.

• ep_int_constr

  Optional construction subset list from the "HB Interior Construction Subset" component. This will be used to assign custom constructions for the adjacent Faces, Apertures, and Doors found in the process of solving adjacency. Note that None values in the input list correspond to constructions that will not change from the default. If no value is input here, the default interior constructions will be assigned using the adjacent Rooms' ConstructionSet.

• rad_int_mod

  Optional Radiance modifier subset list from the "HB Interior Material Subset" component. This will be used to assign custom radiance modifiers for the adjacent Faces, Apertures, and Doors found in the process of solving adjacency. Note that None values in the input list correspond to modifiers that will not change from the default. If no value is input here, the default interior modifiers will be assigned using the adjacent Rooms' ModifierSet.

• adiabatic

  Set to True to have all of the adjacencies discovered by this component set to an adiabatic boundary condition. If False, a Surface boundary condition will be used for all adjacencies. Note that adabatic conditions are not allowed if interior windows are assigned to interior faces. Default: False.

• air_boundary

  Set to True to have all of the face adjacencies discovered by this component set to an AirBoundary face type. Note that AirBoundary face types are not allowed if interior windows are assigned to interior faces. Default: False.

• overwrite

  Boolean to note whether existing Surface boundary conditions should be overwritten. If False or None, only newly-assigned adjacencies will be updated.

• run [Required]

  Set to True to run the component and solve adjacencies.

Outputs

• report

  Reports, errors, warnings, etc.

• adj_rooms

  The input Honeybee Rooms with adjacencies solved between matching Faces.

- [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

  • RoofCeiling

  • Floor

  • AirBoundary

• 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

  • Ground

  • Adiabatic

• 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.

-

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.

Inputs

• rooms [Required]

  Honeybee Rooms which will have their Face boundary conditions set based on the guide surface(s).

• guide [Required]

  Rhino Breps or Meshes that represent the guide surfaces.

• 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. Choose from the following:

  • Wall

  • RoofCeiling

  • Floor

  • AirBoundary

• 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. Choose from the following:

  • Outdoors

  • Ground

  • Adiabatic

• 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.

• 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.

Outputs

• rooms

  The input Rooms with their Face properties changed.

-

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

• hb_objs [Required]

A list of honeybee Rooms or Faces to which Apertures will be added based on the inputs. This can also be an entire honeybee Model for which all Rooms will have Apertures assigned.

• ratio [Required]

A number between 0 and 0.95 for the ratio between the area of the apertures and the area of the parent face. If an array of values are input here, different ratios will be assigned based on cardinal direction, starting with north and moving clockwise.

• subdivide

Boolean to note whether to generate a single window in the center of each Face (False) or to generate a series of rectangular windows using the other inputs below (True). The latter is often more realistic and is important to consider for detailed daylight and thermal comfort simulations but the former is likely better when the only concern is building energy use since energy use doesn't change much while the glazing ratio remains constant. (Default: True).

• win_height

A number for the target height of the output apertures. Note that, if the ratio is too large for the height, the ratio will take precedence and the actual aperture height will be larger than this value. If an array of values are input here, different heights will be assigned based on cardinal direction, starting with north and moving clockwise. (Default: 2 meters).

• sill_height

A number for the target height above the bottom edge of the face to start the apertures. Note that, if the ratio is too large for the height, the ratio will take precedence and the sill_height will be smaller than this value. If an array of values are input here, different heights will be assigned based on cardinal direction, starting with north and moving clockwise. (Default: 0.8 meters).

• horiz_separ

A number for the horizontal separation between individual aperture centerlines. If this number is larger than the parent face's length, only one aperture will be produced. If an array of values are input here, different separation distances will be assigned based on cardinal direction, starting with north and moving clockwise. (Default: 3 meters).

• vert_separ

An optional number to create a single vertical separation between top and bottom apertures. If an array of values are input here, different separation distances will be assigned based on cardinal direction, starting with north and moving clockwise. (Default: 0).

• operable

An optional boolean to note whether the generated Apertures can be opened for ventilation. If an array of booleans are input here, different operable properties will be assigned based on cardinal direction, starting with north and moving clockwise. (Default: False).

Outputs

• report

Reports, errors, warnings, etc.

• hb_objs

The input Honeybee Face, Room or Model with Apertures generated from the input parameters.

-

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]

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.

• sub_faces [Required]

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

Outputs

• hb_obj

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

- [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.

-

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

Inputs

• hb_obj [Required]

  A Honeybee Aperture, Door, Face or a Room to which the shades should be added.

• out_shades

  A list of Honeybee Shade objects to be added to the outside of the input _hb_objs.

• in_shades

  A list of Honeybee Shade objects to be added to the inside of the input _hb_objs. Note that, by default, indoor shades are not used in energy simulations but they are used in all simulations involving Radiance.

Outputs

• hb_obj

  The input Honeybee Aperture, Face or a Room with the input shades added to it.

-

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.

Inputs

• north

  Glazing parameter (boolean, float) for the north.

• east

  Glazing parameter (boolean, float) for the east.

• south

  Glazing parameter (boolean, float) for the south.

• west

  Glazing parameter (boolean, float) for the west.

Outputs

• fac_par

  A list of properties for different cardinal directions to be plugged into the "HB Apertures by Ratio" component or the "HB Louver Shades" component.

- [source code]

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

• hb_objs [Required]

  A list of honeybee Rooms or Faces to which skylight Apertures will be added based on the inputs.

• ratio [Required]

  A number between 0 and 1 for the ratio between the area of the apertures and the area of the parent face.

• x_dim

  The x dimension of the grid cells as a number. (Default: 3 meters)

• y_dim

  The y dimension of the grid cells as a number. Default is None, which will assume the same cell dimension for y as is set for x.

• operable

  An optional boolean to note whether the generated Apertures can be opened for ventilation. Default: False.

Outputs

• report

  Reports, errors, warnings, etc.

• hb_objs

  The input Honeybee Face or Room with skylight Apertures generated from the input parameters.

-

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.

• indoor

  Boolean for whether the extrusion should be generated facing the opposite direction of the aperture normal and added to the Aperture's indoor_shades instead of outdoor_shades. If an array of values are input here, different indoor booleans will be assigned based on cardinal direction, starting with north and moving clockwise. Note that indoor shades are not used in energy simulations but they are used in all simulations involving Radiance. (Default: False).

• ep_constr

  Optional text for an energy construction to be used for all generated shades. This text will be used to look up a construction in the shade construction library. This can also be a custom ShadeConstruction object.

• rad_mod

  Optional Honeybee Modifier to be applied to the input _hb_objs. This can also be text for a modifier to be looked up in the shade modifier library. If an array of text or modifier objects are input here, different modifiers 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.

-

Create Honeybee Shade.

Inputs

• geo [Required]

Rhino Brep or Mesh geometry.

• name

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

• attached

Boolean to note whether the Shade is attached to other geometry. This is automatically set to True if the Shade is assigned to a parent Room, Face, Aperture or Door but will otherwise defalt to False. If the Shade is not easily assignable to a parent object but is attached to the building (eg. a parapet or large roof overhang), then this should be set to True. (Default: False).

• ep_constr

Optional text for the Shade'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.

• ep_trans_sch

Optional text for the Shade's energy transmittance schedule to be looked up in the schedule library. This can also be a custom schedule object. If no energy schedule is input here, the default will be always opaque.

• rad_mod

Optional text for the Shade'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.

Outputs

• report

Reports, errors, warnings, etc.

• shades

Honeybee shades. These can be used directly in radiance and energy 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

• hb_objs [Required]

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

• depth [Required]

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

• shade_count

A positive integer for the number of louvers to generate. If there is an input below for dist_between, an attempt will still be made to meet the shade_count but, if there are more shades than can fit on the input hb_obj, the number of shades will be truncated. If an array of values are input here, different shade counts will be assigned based on cardinal direction, starting with north and moving clockwise. (Default: 1).

• dist_between

A number for the approximate distance between each louver. If an array of values are input here, different distances between louvers will be assigned based on cardinal direction, starting with north and moving clockwise.

• facade_offset

A number for the distance from the louver edge to the facade. If an array of values are input here, different offsets will be assigned based on cardinal direction, starting with north and moving clockwise. (Default: 0).

• angle

A number for the for an angle to rotate the louvers in degrees. If an array of values are input here, different angles will be assigned based on cardinal direction, starting with north and moving clockwise. (Default: 0).

• vertical

Optional boolean to note whether the lovers are vertical. If False, the louvers will be horizontal. If an array of values are input here, different vertical booleans will be assigned based on cardinal direction, starting with north and moving clockwise. (Default: False).

• flip_start

Optional boolean to note whether the side the louvers start from should be flipped. If False, louvers will be generated starting on top or the right side. If True, louvers will start from the bottom or left. If an array of values are input here, different flip start booleans will be assigned based on cardinal direction, starting with north and moving clockwise. Default: False.

• indoor

Optional boolean for whether louvers should be generated facing the opposite direction of the aperture normal and added to the Aperture's indoor_shades instead of outdoor_shades. If an array of values are input here, different indoor booleans will be assigned based on cardinal direction, starting with north and moving clockwise. Note that, by default, indoor shades are not used in energy simulations but they are used in all simulations involving Radiance. (Default: False).

• ep_constr

Optional Honeybee ShadeConstruction to be applied to the input _hb_objs. This can also be text for a construction to be looked up in the shade construction library. If an array of text or construction objects are input here, different constructions will be assigned based on cardinal direction, starting with north and moving clockwise.

• ep_trans_sch

Optional schedule for the transmittance to be applied to the input _hb_objs in energy simulation. If no energy schedule is input here, the default will be always opaque.

• rad_mod

Optional Honeybee Modifier to be applied to the input _hb_objs. This can also be text for a modifier to be looked up in the shade modifier library. If an array of text or modifier objects are input here, different modifiers 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 louvered shades added to it.

- [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]

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]

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

Inputs

• hb_objs [Required]

  Any Honeybee geometry object (eg. Room, Face, Aperture, Door or Shade) to be rotated by an angle. This can also be a Honeybee Model object to be rotated.

• angle [Required]

  An angle for rotation in degrees.

• origin

  A Point3D for the origin around which the object will be rotated. If None, it will be rotated from each object's center point unless the input object is a Model, in which case, it will be rotated from the world origin (0, 0, 0).

• axis

  A Vector3D axis representing the axis of rotation. If None, the axis will be a Z-vector (0, 0, 1) and the object will be rotated within the XY plane.

• 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 rotated by the input angle.

-

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.

-

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

Inputs

• hb_objs [Required]

  Any Honeybee geometry object (eg. Room, Face, Aperture, Door or Shade) to be scaled by a factor. This can also be a Honeybee Model object to be scaled.

• factor [Required]

  A number representing how much the object should be scaled.

• origin

  A Point3D representing the origin from which to scale. If None, it will be scaled from each object's center point unless the input object is a Model, in which case, it will be scaled from the world origin (0, 0, 0).

• 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 scaled by the input factor.

-

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.

Inputs

• launch [Required]

  Set to True to run the component and launch a browser window that visualizes recipe execution steps.

Outputs

• report

  Reports, errors, warnings, etc.

- [source code]

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

• rooms [Required]

Honeybee Rooms which will have their apertures set based on their relation to the guide surface(s).

• guide [Required]

Rhino Breps or Meshes that represent the guide surfaces.

• ratio [Required]

A number between 0 and 0.95 for the ratio between the area of the apertures and the area of the parent face.

• subdivide

Boolean to note whether to generate a single window in the center of each Face (False) or to generate a series of rectangular windows using the other inputs below (True). The latter is often more realistic and is important to consider for detailed daylight and thermal comfort simulations but the former is likely better when the only concern is building energy use since energy use doesn't change much while the glazing ratio remains constant. (Default: True).

• win_height

A number for the target height of the output apertures. Note that, if the ratio is too large for the height, the ratio will take precedence and the actual aperture height will be larger than this value. (Default: 2 meters).

• sill_height

A number for the target height above the bottom edge of the face to start the apertures. Note that, if the ratio is too large for the height, the ratio will take precedence and the sill_height will be smaller than this value. If an array of values are input here, different heights will be assigned based on cardinal direction, starting with north and moving clockwise. Default: 0.8 meters.

• horiz_separ

A number for the horizontal separation between individual aperture centerlines. If this number is larger than the parent face's length, only one aperture will be produced. If an array of values are input here, different separation distances will be assigned based on cardinal direction, starting with north and moving clockwise. Default: 3 meters.

• vert_separ

An optional number to create a single vertical separation between top and bottom apertures. If an array of values are input here, different separation distances will be assigned based on cardinal direction, starting with north and moving clockwise.

• operable

An optional boolean to note whether the generated Apertures can be opened for ventilation. If an array of booleans are input here, different operable properties will be assigned based on cardinal direction, starting with north and moving clockwise.

Outputs

• rooms

The input Rooms with their Face properties changed.

-

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

• hb_objs [Required]

A list of honeybee Rooms or Faces to which Apertures will be added based on the inputs. This can also be an entire honeybee Model for which all Rooms will have Apertures assigned.

• win_height

A number for the target height of the output apertures. Note that, if the window height is larger than the height of the wall, the generated windows will have a height equal to the wall height in order to avoid having windows extend outside the wall face. If an array of values are input here, different heights will be assigned based on cardinal direction, starting with north and moving clockwise. (Default: 2 meters).

• win_width

A number for the target width the output apertures. Note that, if the window width is larger than the width of the wall, the generated windows will have a width equal to the wall width in order to avoid having windows extend outside the wall face. If an array of values are input here, different widths will be assigned based on cardinal direction, starting with north and moving clockwise. (Default: 1.5 meters).

• sill_height

A number for the target height above the bottom edge of the face to start the apertures. Note that, if the window height is too large to acoomodate the sill height input here, the window height will take precedence and the sill height will be smaller than this value. If an array of values are input here, different heights will be assigned based on cardinal direction, starting with north and moving clockwise. (Default: 0.8 meters).

• horiz_separ

A number for the horizontal separation between individual aperture centerlines. If this number is larger than the parent face's length, only one aperture will be produced. If an array of values are input here, different separation distances will be assigned based on cardinal direction, starting with north and moving clockwise. (Default: 3 meters).

• operable

An optional boolean to note whether the generated Apertures can be opened for ventilation. If an array of booleans are input here, different operable properties will be assigned based on cardinal direction, starting with north and moving clockwise. (Default: False).

Outputs

• report

Reports, errors, warnings, etc.

• hb_objs

The input Honeybee Face, Room or Model with Apertures generated from the input parameters.

- [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]

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.

Inputs

• hb_obj [Required]

  Any honeybee-core object (eg. Room, Face, Shade, Aperture) or any honeybee extension object (eg. energy construction, radiance modifier) for which the identifier should be changed.

• id [Required]

  Text for the identifier of the object. Note that, if this identifier does not conform to acceptable values of the object type (eg. no spaces for a radiance modifier id), then an exception will be thrown.

Outputs

• hb_obj

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

- [source code]

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.

Inputs

• rooms [Required]

Honeybee Rooms to which the input _multipier should be assigned.

• multiplier [Required]

An integer noting how many times the Rooms are repeated. This can also be an array of integers, which align with the input _rooms and will be matched to them accordingly.

• excl_floor

Boolean to indicate whether the floor area of the room is excluded from the Model it is a part of. Note that this will not affect the floor_area property of this Room but it will ensure the Room's floor area is excluded from any calculations when the Room is part of a Model and when it is simulated in EnergyPlus.

Outputs

• report

...

• rooms

The input Rooms with their multipliers edited.

- [source code]

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.

Inputs

• rooms [Required]

Honeybee Rooms which will have their Face boundary conditions set based on their spatial relation to the _ground geometry below.

• ground [Required]

Rhino Breps or Meshes that represent the Ground.

• reset

A Boolean to note whether the _ground geometry simply adds additional ground boundary conditions to the _rooms (False) or it resets all existing ground boundary conditions to only exist at or below the _ground geometry (True). (Default: False).

Outputs

• rooms

The input Rooms with their Ground boundary conditions set.

-

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

• rooms [Required]

  Honeybee Rooms to which the input _story should be assigned.

• story [Required]

  Text for the story identifier to which the rooms belong.

Outputs

• report

  ...

• rooms

  The input Rooms with their stories set.

- [source code]

Get the straight skeleton of any horizontal planar geometry.

This is can also be used to generate core/perimeter sub-polygons if an offset is input AND the straight skeleton is not self-intersecting. In the event of a self-intersecting straight skeleton, the output line segments can still be used to assist with the manual creation of core/perimeter offsets.

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).

Inputs

• floor_geo [Required]

Horizontal Rhino surfaces for which the straight skeleton will be computed.

• offset

An optional positive number that will be used to offset the perimeter of the geometry to output core/perimeter polygons. If a value is plugged in here and the straight skeleton is not self-intersecting, perim_poly and core_poly will be ouput.

Outputs

• polyskel

A list of line segments that represent the straight skeleton of the input _floor_geo. This will be output from the component no matter what the input _floor_geo is.

• perim_poly

A list of breps representing the perimeter polygons of the input floor_geo. This will only be ouput if an offset is input and the straight skeleton is not self-intersecting.

• core_poly

A list of breps representing the core polygons of the input floor_geo. This will only be ouput if an offset is input and the straight skeleton is not self-intersecting, and the offset is not so great as to eliminate the core.

• Visualize All

• Visualize Normals

• Visualize Quick

• Visualize Wireframe

• Face Attributes

• Room Attributes

• Color Face Attributes

• Color Room Attributes

• Label Faces

• Label Rooms

• Visualize by BC

• Visualize by Type

• Check Versions

• Config

• Geometry Properties

-

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

• hb_objs [Required]

A Honeybee Model, Room, Face, Shade, Aperture, or Door for which points and vectors will be output in the Rhino scene to show the object's orientation.

Outputs

• points

Points that lie at the center of each surface of the connected _hb_objs. These should be connected to the "Anchor" input of a native Grasshopper "Vector Display" component.

• vectors

Normal vectors for each surface of the connected _hb_objs. These should be connected to the "Vector" input of a native Grasshopper "Vector Display" component.

-

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

Inputs

• hb_objs [Required]

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

Outputs

• geo

The Rhino version of the Honeybee geometry object, which will be visible in the Rhino scene.

-

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.

Inputs

• hb_objs [Required]

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

Outputs

• geo

The Rhino version of the Honeybee geometry object, which will be visible in the Rhino scene.

- [source code]

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

Inputs

• hb_objs [Required]

A Honeybee Model, Room, Face, Shade, Aperture, or Door to be previewed as a wire frame in the Rhino scene.

Outputs

• geo

The Rhino wireframe version of the Honeybee geometry object, which will be visible in the Rhino scene.

- [source code]

Provides a list of preset values to choose from

- [source code]

Provides a list of preset values to choose from

- [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]

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

• hb_objs [Required]

  Honeybee Faces, Rooms or a Model to be labeled with their attributes in the Rhino scene.

• attribute

  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. Default: "name".

• sub_faces

  Set to "True" to have the component label the window surfaces in the model instead of the opaque surfaces. By default, this is set to "False" to label just the opaque surfaces.

• txt_height

  An optional number for the height of the text in the Rhino scene. The default is auto-calculated based on the dimensions of the input geometry.

• font

  An optional name of a font in which the labels will display. This must be a font that is installed on this machine in order to work correctly. Default: "Arial".

Outputs

• label_text

  The text with which each of the faces or sub-faces are labeled.

• base_pts

  The base point for each of the text labels.

• labels

  The text objects that are displaying within the Rhino scene.

• wire_frame

  A list of curves representing the outlines of the faces or sub-faces. This is useful for understanding which geometry elements each label corresponds to.

-

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.

-

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

• rooms_model [Required]

  An array of honeybee Rooms or honeybee Models to be labeled with their attributes in the Rhinoscene.

• attribute

  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. Default: "name".

• txt_height

  An optional number for the height of the text in the Rhino scene. The default is auto-calculated based on the dimensions of the input geometry.

• font

  An optional name of a font in which the labels will display. This must be a font that is installed on this machine in order to work correctly. Default: "Arial".

Outputs

• label_text

  The text with which each of the rooms are labeled.

• base_pts

  The base planes for each of the text labels.

• labels

  The text objects that are displaying within the Rhino scene.

• wire_frame

  A list of curves representing the outlines of the rooms. This is useful for understanding which geometry elements each label corresponds to.

- [source code]

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

Inputs

• hb_objs [Required]

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

Outputs

• outdoors

Rhino geometry for the objects with an Outdoors boundary condition.

• surface

Rhino geometry for the objects with a Surface (interior) boundary condition.

• ground

Rhino geometry for the objects with a Ground boundary condition.

• adiabatic

Rhino geometry for the objects with an adiabatic (no heat flow) boundary condition.

• other

Rhino geometry for all objects with a boundary condition other than the four above. All shade geometry will also be added to this list.

• wire_frame

A list of lines representing the outlines of the rooms.

- [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.

• roofs

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

• ceilings

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

• exterior_floors

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

• interior_floors

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

• air_walls

  Rhino geometry for the AirWalls.

• apertures

  Rhino geometry for the Apertures with an Outdoors boundary condition.

• interior_apertures

  Rhino geometry for the Apertures with a Surface boundary condition.

• doors

  Rhino geometry for the Doors with an Outdoors boundary condition.

• interior_doors

  Rhino geometry for the Doors with a Surface boundary condition.

• outdoor_shades

  Rhino geometry for the Shades assigned to the outdoors of their parent objects. This also includes all orphaned shades of a model.

• indoor_shades

  Rhino geometry for the Shades assigned to the indoors of their parent objects.

• wire_frame

  A list of lines representing the outlines of the rooms.

- [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).

-

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.

• rad_install

  The path to Radiance installation folder if it exists.

• os_install

  The path to OpenStudio installation folder if it exists.

• ep_install

  The path to EnergyPlus installation folder if it exists.

• hb_os_gem

  The path to the honeybee_openstudio_gem if it exists. This gem contains libraries and measures for translating between Honeybee JSON schema and OpenStudio Model schema (OSM).

• standards

  The path to the library of standards if it exists. This library contains the default Modifiers, ModifierSets, Constructions, ConstructionSets, Schedules, and ProgramTypes. It can be extended by dropping IDF or Honeybee JOSN files into the appropriate sub-folder.

• asset_report

  A report of all the assets that have been loaded from the standards library.

• default_sim

  The path to the default simulation folder (where simulation files are written if not specified by the user.).

• Faces by Attribute

• Rooms by Attribute

• Rooms by Floor Height

• Rooms by Orientation

• Faces by BC

• Faces by Type

-

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

• hb_objs [Required]

An array of honeybee Rooms, Faces, Apertures, Doors or Shades to be separated by their attributes in the Rhino scene.

• attribute [Required]

Text for the name of the Face attribute with which the 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 attributes of that extension.

Outputs

• values

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

• hb_objs

A data tree of honeybee faces and sub-faces with each branc of the tree representing a different attribute value.

-

Get geometry properties of honeybee Rooms or a honeybee Model.

Inputs

• rooms [Required]

A list of honeybee Rooms for which or geometry properties will be output. This can also be an entire honeybee Model.

Outputs

• ext_wall_area

A number for the total area of walls in the honeybee rooms with an Outdoors boundary condition (in Rhino model units).

• ext_win_area

A number for the total area of windows in the honeybee rooms with an Outdoors boundary condition (in Rhino model units).

• volume

A number for the volume of the honeybee rooms (in Rhino model units).

• floor_area

A number for the floor area of the honeybee rooms (in Rhino model units). When a Model is connected, the floor area will exclude plenums and other Rooms with that have a True exclude_floor_area property.

• floor_ep_constr

A number for the floor area of the Room accounting for the thickness of EnergyPlus wall constructions. (in Rhino model units). When a Model is connected, the floor area will exclude plenums and other Rooms with that have a True exclude_floor_area property.

- [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.

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.

- [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]

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.

• core_rooms

  A list of honeybee rooms with no identifiable orientation.

- [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.

• ground

  The objects with a Ground boundary condition.

• adiabatic

  The objects with an adiabatic (no heat flow) boundary condition.

• other

  All objects with a boundary condition other than the four above. All shades will also be added to this list.

- [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]

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.

• roofs

  The RoofCeilings with an Outdoors or Ground boundary condition.

• ceilings

  The RoofCeilings with a Surface or Adiabatic boundary condition.

• exterior_floors

  The Floors with an Outdoors or Ground boundary condition.

• interior_floors

  The Floors with a Surface or Adiabatic boundary condition.

• air_walls

  The AirWalls.

• apertures

  The Apertures with an Outdoors boundary condition.

• interior_apertures

  The Apertures with a Surface boundary condition.

• doors

  The Doors with an Outdoors boundary condition.

• interior_doors

  The Doors with a Surface boundary condition.

• outdoor_shades

  The Shades assigned to the outdoors of their parent objects. This also includes all orphaned shades of a model.

• indoor_shades

  The Shades assigned to the indoors of their parent objects.

-

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.

Inputs

• hb_obj [Required]

A Honeybee object to be serialized to a string.

Outputs

• hb_str

A text string that completely describes the honeybee object. This can be serialized back into a honeybee object using the "HB String to Object" coponent.

- [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.

-

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]

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').

• folder

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

• 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 .pkl file is saved.

-

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.

Inputs

• model [Required]

A Honeybee Model object to be written to a gbXML file.

• name

A name for the file to which the honeybee objects will be written. If unspecified, it will be derived from the model identifier.

• folder

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

• int_floors

A boolean to note whether all interior horizontal faces should be written with the InteriorFloor type instead of the combination of InteriorFloor and Ceiling that happens by default with OpenStudio gbXML serialization. (Default: False).

• triangulate

Boolean to note whether sub-faces (including Apertures and Doors) should be triangulated if they have more than 4 sides (True) or whether they should be left as they are (False). This triangulation is necessary when exporting directly to EnergyPlus since it cannot accept sub-faces with more than 4 vertices. However, it is not a general requirement of gbXML or all of the simulation engines that gbXML can import to/from. (Default: False).

• full_geo

Boolean to note whether space boundaries and shell geometry should be included in the exported gbXML vs. just the minimal required non-manifold geometry. Setting to True to include the full geometry will increase file size without adding much new infomration that doesn't already exist in the file. However, some gbXML interfaces need this geometry in order to properly represent and display room volumes. (Default: False).

• dump [Required]

Set to "True" to save the honeybee model to a gbXML file.

Outputs

• report

Errors, warnings, etc.

• gbxml

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

- [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 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 and, the HBJSON format should be used whenever lossless file transfer is needed.

Inputs

• model_file [Required]

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

• 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.

-

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.

Inputs

• hbjson [Required]

  A file path to a Model HBJSON which will be upgraded to the currently installed version of the Honeybee Model schema (or a specific version specified below).

• version

  Text to indicate the version to which the Model HBJSON will be updated (eg. 1.41.2). Versions must always consist of three integers separated by periods. If None, the Model HBJSON will be updated to the currently installed version of honeybee-schema.

• name

  A name for the file to which the honeybee objects will be written. By default, it will have the same name as the input file but with "UPDATED" appended to the file name.

• folder

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

• validate

  Boolean to note whether the Honeybee Model should be validated and checked for errors after it has been updated. This includes basic properties like adjacency and duplicate identifier checks as well as geometry checks for planarity, room solidity, etc.

• update [Required]

  Set to "True" to update the Model HBJSON to the currently installed version.

Outputs

• report

  Reports, errors, warnings, etc.

• hbjson

  The file path to the updated HBJSON.

- [source code]

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.

Inputs

• model [Required]

A Honeybee Model object to be validated. This can also be the file path to a Model HBJSON that will be validated.

• validate [Required]

Set to "True" to validate the the Model and get a report of all issues with the model.

Outputs

• report

A report summarizing any issues with the input _model. If anything is invalid about the input model, this component will give a warning and this report will contain information about the specific parts of the model that are invalid. Otherwise, this report will simply say that the input model is valid.