1 of 100

HB-Energy Primer

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

Honeybee-energy extends the core capabilities of the honeybee plugin to enable enable simulation of models in EnergyPlus. Honeybee-energy leverages the OpenStudio SDK in order to add energy simulation properties and capabilities.

Installation

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

Resources

Post your questions to Ladybug Tools forum and see the honeybee-grasshopper-energy 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.

Components

0 :: Basic Properties

Building Vintages

- [source code]

Provides a list of available building vintages in the library.

Climate Zones

- [source code]

Provides a list of available climate zones in the library.

Face Energy Attributes

- [source code]

List of all energy attirbutes assigned to Honeybee Faces and Subfaces.

Room Energy Attributes

- [source code]

List of all energy attirbutes assigned to Honeybee Rooms.

Blend ProgramTypes

- [source code]

Create a ProgramType object by blending other ProgramTypes together using a weighted average based on program ratios.

Inputs

name
Text to set the name for the ProgramType and to be incorporated into a unique ProgramType identifier.
programs [Required]
A list of ProgramType objects that will be averaged together to make a new ProgramType.
ratios
A list of fractional numbers with the same length as the input programs that sum to 1. These will be used to weight each of the ProgramType objects in the resulting average. If None, the input program objects will be weighted equally. Default: None.

Outputs

program
A ProgramType object that's a weighted average between the input _programs.

Building Programs

Provides a list of available building programs in the ProgramType library.

ProgramType

Create a ProgramType object possessing all schedules and loads defining the usage of a space.

ProgramTypes can be assigned to Honeybee Rooms to specify all default schedules and loads on the Room.

Inputs

name
Text to set the name for the ProgramType and to be incorporated into a unique ProgramType identifier.
base_program
An optional ProgramType object that will be used as the starting point for the new ProgramType output from this component. This can also be text for the name of a ProgramType within the library such as that output from the "HB Search Program Types" component. If None, a Plenum program type will be used as the base with no loads, setpoints, or ventilation requirements assigned.
people
A People object to describe the occupancy of the program. If None, no occupancy will be assumed for the program. (Default: None).
lighting
A Lighting object to describe the lighting usage of the program. If None, no lighting will be assumed for the program. (Default: None).
electric_equip
An ElectricEquipment object to describe the usage of electric equipment within the program. If None, no electric equipment will be assumed for the program. (Default: None).
gas_equip
A GasEquipment object to describe the usage of gas equipment within the program. If None, no gas equipment will be assumed for the program. (Default: None).
hot_water
A ServiceHotWater object to describe the usage of hot water within the program. If None, no hot water will be assumed for the program. (Default: None).
infiltration
An Infiltration object to describe the outdoor air leakage of the program. If None, no infiltration will be assumed for the program. (Default: None).
ventilation
A Ventilation object to describe the minimum outdoor air requirement of the program. If None, no ventilation requirement will be assumed for the program. (Default: None).
setpoint
A Setpoint object to describe the temperature and humidity setpoints of the program. If None, the ProgramType cannot be assigned to a Room that is conditioned. (Default: None).

Outputs

program
A ProgramType object that can be assigned to Honeybee Rooms in order to specify all default schedules and loads on the Room.

Search Programs

Search for available ProgramTypes within the honeybee energy standards library.

Note that the Room ProgramTypes output from this component effectively map to space types within OpenStudio.

Inputs

bldg_prog
Text for the building program to search (eg. "LargeOffice", "MidriseApartment", etc.). The Honeybee "Building Programs" component lists all of the building programs available in the library. If None, all ProgramTypes within the library will be output (filtered by keywords_ below).
vintage
Text for the building vintage to search (eg. "2019", "pre_1980", etc.). The Honeybee "Building Vintages" component lists all of the vintages available in the library. Default: "2019" (for ASHRAE 90.1 2019 | IECC 2015). Note that vintages are often called "templates" within the OpenStudio standards gem and so this property effective maps to the standards gem "template".
keywords
Optional keywords to be used to narrow down the output list of room programs. If nothing is input here, all available room programs will be output.

Outputs

room_prog
A list of room program identifiers that meet the input criteria and can be applied to Honeybee Rooms.

ConstructionSet

- [source code]

Create a ConstructionSet object containing all energy constructions needed to create an energy model. ConstructionSets can be assigned to Honeybee Rooms to specify all default constructions on the Room.

Inputs

name
Text to set the name for the ConstructionSet and to be incorporated into a unique ConstructionSet identifier.
base_constr_set
An optional ConstructionSet object that will be used as the starting point for the new ConstructionSet output from this component. This can also be text for the name of a ConstructionSet within the library such as that output from the "HB Search Construction Sets" component. If None, the Honeybee "Generic Default Construction Set" will be used as the base.
exterior_subset
A construction subset list from the "HB Exterior Construction Subset" component. Note that None values in this list correspond to no change to the given construction in the baseconstr_set.
ground_subset
A construction subset list from the "HB Ground Construction Subset" component. Note that None values in this list correspond to no change to the given construction in the baseconstr_set.
interior_subset
A construction subset list from the "HB Interior Construction Subset" component. Note that None values in this list correspond to no change to the given construction in the baseconstr_set.
subface_subset
A construction subset list from the "HB Subface Subset" component. Note that None values in this list correspond to no change to the given construction in the baseconstr_set.

Outputs

constr_set
A ConstructionSet object that can be assigned to Honeybee Rooms in order to specify all default constructions on the Room.

Construction Set by Climate

Get a ConstructionSet from the standards library using a climate zone, building vintage and construction type.

Inputs

climate_zone [Required]
An integer between 1 and 8 for the ASHRAE climate zone in which the building is located. ASHRAE climate zones exist for all locations on Earth and can typically be looked up online or within the .stat file that downloads next to the .epw file. The climate zone is used to determine the amount of code-recommended insulation and solar heat gain protection for the construction set. The Honeybee "Climate Zones" component lists all of the climate zones supported by the library.
vintage
Text for the building vintage to search (eg. "2019", "pre_1980", etc.). The Honeybee "Building Vintages" component lists all of the vintages available in the library. Default: "2019" (for ASHRAE 90.1 2019). Note that vintages are often called "templates" within the OpenStudio standards gem and so this property effective maps to the standards gem "template".
constr_type
Text for the construction type of the set. (eg. "SteelFramed", "WoodFramed", "Mass", "Metal Building"). The Honeybee "Construction Types" component lists all of the construction types available in the library.

Outputs

constr_set
A ConstructionSet identifier that can be applied to Honeybee Rooms.

Construction Types

- [source code]

Provides a list of available building construction types in the ConstructionSet library.

Search Construction Sets

Search for available ConstructionSets within the honeybee energy standards library.

Inputs

keywords
Optional keywords to be used to narrow down the output list of construction sets. If nothing is input here, all available construction sets will be output.
join_words
If False or None, this component will automatically split any strings of multiple keywords (spearated by spaces) into separate keywords for searching. This results in a greater liklihood of finding an item in the search but it may not be appropropriate for all cases. You may want to set it to True when you are searching for a specific phrase that includes spaces. (Default: False).

Outputs

constr_sets
A list of ConstructionSet identifiers that can be applied to Honeybee Rooms.

Exterior Construction Subset

- [source code]

Create a list of exterior constructions that can be used to edit or create a ConstructionSet object.

Inputs

exterior_wall
A construction object for exterior walls (or text for the identifier of the construction within the library).
exterior_roof
A construction object for exterior roofs (or text for the identifier of the construction within the library).
exposed_floor
A construction object for exposed floors (or text for the identifier of the construction within the library).

Outputs

exterior_set
A list of exterior constructions that can be used to edit or create a ConstructionSet object.

Ground Construction Subset

- [source code]

Create a list of ground constructions that can be used to edit or create a ConstructionSet object.

Inputs

ground_wall
A construction object for underground walls (or text for the identifier of the construction within the library).
ground_roof
A construction object for underground roofs (or text for the identifier of the construction within the library).
ground_floor
A construction object for ground-contact floors (or text for the identifier of the construction within the library).

Outputs

ground_set
A list of ground constructions that can be used to edit or create a ConstructionSet object.

Interior Construction Subset

- [source code]

Create a list of interior constructions that can be used to edit or create a ConstructionSet object.

Inputs

interior_wall
A construction object for interior walls (or text for the identifier of the construction within the library).
ceiling
A construction object for ceilings (or text for the identifier of the construction within the library).
interior_floor
A construction object for interior floors (or text for the identifier of the construction within the library).
interior_window
A construction object for all apertures with a Surface boundary condition. This can also be text for the identifier of the construction within the library.
interior_door
A construction object for all opaque doors with a Surface boundary condition. This can also be text for the identifier of the construction within the library.
int_glass_door
A construction object for all glass doors with a Surface boundary condition. This can also be text for the identifier of the construction within the library.

Outputs

interior_set
A list of interior constructions that can be used to edit or create a ConstructionSet object.

Subface Subset

Create a list of exterior subface (apertures + doors) constructions that can be used to edit or create a ConstructionSet object.

Inputs

window
A construction object for apertures with an Outdoors boundary condition and a Wall face type for their parent face. This can also be text for the identifier of the construction within the library.
skylight
A construction object for apertures with an Outdoors boundary condition and a RoofCeiling or Floor face type for their parent face. This can also be text for the identifier of the construction within the library.
operable
A construction object for apertures with an Outdoors boundary condition and True is_operable property. This can also be text for the identifier of the construction within the library.
exterior_door
A construction object for opaque doors with an Outdoors boundary condition and a Wall face type for their parent face. This can also be text for the identifier of the construction within the library.
overhead_door
A construction object for opaque doors with an Outdoors boundary condition and a RoofCeiling or Floor face type for their parent face. This can also be text for the identifier of the construction within the library.
glass_door
A construction object for all glass doors with an Outdoors boundary condition. This can also be text for the identifier of the construction within the library.

Outputs

subface_set
A list of exterior subface constructions that can be used to edit or create a ConstructionSet object.

Adiabatic by Type

Make boundary conditions of Rooms or Faces adiabatic by face type.

Inputs

hb_objs [Required]
Honeybee Faces or Rooms to which adiabatic boundary conditions will be assigned.
exterior_walls
If True, all exterior walls of the input Rooms or Faces will be set to adiabatic. This can also be a list of boolean values and different adiabatic values will be assigned based on the cardinal direction, starting with north and moving clockwise.
roofs
If True, all exterior roofs of the input Rooms or Faces will be set to adiabatic.
exposed_floors
If True, all exposed floors of the input Rooms or Faces will be set to adiabatic.
interior_walls
If True, all interior walls of the input Rooms or Faces will be set to adiabatic.
interior_floors
If True, all interior floors and ceilings of the input Rooms or Faces will be set to adiabatic.

Outputs

hb_objs
The input honeybee objects with their boundary conditions edited.

Plenum

Turn Honeybee Rooms into Plenums with no internal loads.

This includes removing all people, lighting, equipment, hot water, and mechanical ventilation. By default, the heating/cooling system and setpoints will also be removed but they can optionally be kept. Infiltration is kept by default but can optionally be removed as well.

This is useful to appropriately assign properties for closets, underfloor spaces, and drop ceilings.

Inputs

rooms [Required]

Honeybee Rooms to be converted into plenums.

conditioned

Boolean to indicate whether the plenum is conditioned with a heating/cooling system. If True, the setpoints of the Room will also be kept in addition to the heating/cooling system (Default: False).

remove_infilt

Boolean to indicate whether infiltration should be removed from the Rooms. If False, infiltration will be preserved and will be the only load assinged to the plenum. (Default: False).

include_floor

Boolean to indicate whether the floor area of the plenum contributes to 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

rooms

Rooms that have had their interinal loads removed to reflect a plenum space.

Ground

Change the properties of Honeybee Rooms to reflect those of a ground surface.

This is particularly useful for setting up outdoor thermal comfort maps that account for the surface temperature of the ground. Modeling the ground as a room this way will ensure that shadows other objects cast upon it are accounted for along with the storage of heat in the ground surface.

The turning of a Room into a ground entails:

Setting all constructions to be indicative of a certain soil type. * Setting all Faces except the roof to have a Ground boundary condition. * Removing all loads and schedules assigned to the Room.

All values for the typical soil_types are taken from the Engineering Toolbox, specifically these pages: Soil Conductivity - http://www.engineeringtoolbox.com/thermal-conductivity-d_429.html Soil Density - http://www.engineeringtoolbox.com/dirt-mud-densities-d_1727.html Soil Heat Capacity - http://www.engineeringtoolbox.com/specific-heat-capacity-d_391.html

Inputs

rooms [Required]

Honeybee Rooms to be converted into ground objects.

soil_constr

An OpaqueConstruction that reflects the soil type of the ground. This can also be text for a construction to be looked up in the opaque construction library. If a multi-layered construction is input, the multiple layers will only be used for the roof Face of the Room and all other Faces will get a construction with the inner-most layer assigned. Some common types of soil constructions contained in the default honeybee standards library are listed below. (Default: Concrete Pavement). Grassy Lawn Dry Sand Dry Dust Moist Soil Mud Concrete Pavement Asphalt Pavement Solid Rock

Outputs

rooms

Rooms that have had their properties altered to be representative of ground conditions.

Internal Mass

Assign internal thermal masses to Rooms, which can be used to account for the effects of furniture inside Rooms or other massive building components like staircases, hearths, etc.

The component accepts either Rhino geometry (representing furniture or massive elements) or a numerical value of the mass's surface area. Several of these components can be used in a series to descibe different internal masses made of different materials.

Note that internal masses assigned this way cannot "see" solar radiation that may potentially hit them and, as such, caution should be taken when using this component with internal mass objects that are not always in shade. Masses are factored into the the thermal calculations of the Room by undergoing heat transfer with the indoor air.

Inputs

rooms [Required]
Honeybee Rooms to which internal masses should be assigned.
geo_or_area [Required]
A list of Rhino breps or meshes representing the surfaces of internal masses that are exposed to the air of the Room. Alternatively, this can be a number or list of numbers representing the surface area of the internal masses (in square meters) that are exposed to the Room air.
In the case of Rhino geometry representing the surfaces of internal masses, this component will determine which Room the geometry is in. However, geometry must lie COMPLETELY inside a single Room and cannot span between Rooms or span outside the building. If a geometry lies between two Rooms, it should be split in two along the boundary between the Rooms. Also note that geometries are assumed to have only one side exposed to the Room air so, if they are meant to represent a 2-sided object, the geometry should be duplicated and offset.
In the case of numbers representing the the surface area of the internal masses, inputs can be either a single number (which will be used to put internal masses into all Rooms using the specified surface area), or it can be a list of numbers that matches the input Rooms, which can be used to assign different amounts of mass surface area to different Rooms. All numbers are assumed to be in square meters.
construction [Required]
An OpaqueConstruction object that represents the material that the internal thermal mass is composed of. This can also be text for the identifier of the construction within the library.
name
An optional text name for the internal mass. This can be useful for keeping track of different internal masses when using several of these components in series. If unspecified, a unique one will be generated.

Outputs

report
Reports, errors, warnings, etc.
rooms
The input Rooms with internal masses assigned.

Other Side Temperature

- [source code]

Create a boundary condition representing a custom temperature and/or heat transfer coefficient on the other side of a face.

Inputs

temperature

A temperature value in Celsius to note the temperature on the other side of the object. If unspecified, the outdoor air temperature will be used.

heat_coeff

A value in W/m2-K to indicate the combined convective/radiative film coefficient. If equal to 0, then the specified temperature above is equal to the exterior surface temperature. Otherwise, the temperature above is considered the outside air temperature and this coefficient is used to determine the difference between this outside air temperature and the exterior surface temperature. (Default: 0).

Outputs

A BoundaryCondition object that can be assigned to any honeybee Face object (using the "HB Face" component or the "HB Properties by Guide Surface").

Patch Missing Adjacency

- [source code]

Set any Faces of Rooms with missing adjacencies to Adiabatic.

This is useful when simulating a subset of Rooms from a larger Model.

If any of the Faces with missing adjacencies have sub-faces, these will be removed in order to accommodate the adiabatic condition. Similarly, if the Face is an AirBoundary, the type will be set to a Wall.

Inputs

rooms [Required]

A list of Honeybee Rooms which will have its adjacencies patched with Adiabatic boundary conditions. This can also be an entire honyebee Model. Any adjacnecy not found across all of the rooms will be replaced with an Adiabatic boundary.

Outputs

rooms

Rooms that have had their missing adjacencies patched.

1 :: Constructions

Search Constructions

- [source code]

Search for available Constructions within the honeybee energy standards library.

Inputs

keywords
Optional keywords to be used to narrow down the output list of constructions. If nothing is input here, all available constructions will be output.
join_words
If False or None, this component will automatically split any strings of multiple keywords (spearated by spaces) into separate keywords for searching. This results in a greater liklihood of finding an item in the search but it may not be appropropriate for all cases. You may want to set it to True when you are searching for a specific phrase that includes spaces. Default: False.

Outputs

opaque_constrs
A list of opaque constructions within the honeybee energy standards library (filtered by keywords_ if they are input).
window_constrs
A list of window constructions within the honeybee energy standards library (filtered by keywords_ if they are input).
shade_constrs
A list of shade constructions within the honeybee energy standards library (filtered by keywords_ if they are input).

Search Materials

Search for available Materials within the honeybee energy standards library.

Inputs

keywords
Optional keywords to be used to narrow down the output list of materials. If nothing is input here, all available materials will be output.
join_words
If False or None, this component will automatically split any strings of multiple keywords (spearated by spaces) into separate keywords for searching. This results in a greater liklihood of finding an item in the search but it may not be appropropriate for all cases. You may want to set it to True when you are searching for a specific phrase that includes spaces. Default: False.

Outputs

opaque_mats
A list of opaque materials within the honeybee energy standards library (filtered by keywords_ if they are input).
window_mats
A list of window materials within the honeybee energy standards library (filtered by keywords_ if they are input).

Deconstruct Construction

- [source code]

Deconstruct an opaque or window construction into its constituient materials.

Inputs

constr [Required]
An opaque or window construction to be deconstructed. This can also be text for an opaque or window construction to be looked up in the construction library.

Outputs

materials
List of material objects that make up the construction (ordered from outside to inside).
layers
List of material identifiers that make up the construction (ordered from outside to inside).
r_val_si
R-value of the construction in m2-K/W. Note that R-values do NOT include the resistance of air films on either side of the construction.
r_val_ip
R-value of the construction in h-ft2-F/Btu. Note that R-values do NOT include the resistance of air films on either side of the construction.
u_fac_si
U-factor of the construction in W/m2-K. Note that U-factors include the resistance of air films on either side of the construction.
u_fac_ip
U-factor of the construction in Btu/h-ft2-F. Note that U-factors include the resistance of air films on either side of the construction.
shgc
The estimated solar heat gain coefficient (SHGC) of the construction. This value is produced by finding the solution to the relationship between U-value, Solar Transmittance, and SHGC as defined for the simple glazing system material in EnergyPlus. More information can be found at https://bigladdersoftware.com/epx/docs/9-5/engineering-reference/ on this partticular sub-page of the engineering reference: window-calculation-module.html#step-4.-determine-layer-solar-transmittance
t_sol
The unshaded shortwave solar transmittance of the construction at normal incidence. Note that 'unshaded' in this case means that all blind + shade materials in the construction are ignored.
t_vis
The unshaded visible transmittance of the window at normal incidence. Note that 'unshaded' in this case means that all blind + shade materials in the construction are ignored.

Deconstruct ConstructionSet

- [source code]

Deconstruct a construction set into its constituient exterior constructions.

Inputs

constr_set [Required]
A construction set to be deconstructed. This can also be text for a construction set to be looked up in the construction set library.

Outputs

exterior_wall
A construction object for the set's exterior walls.
exterior_roof
A construction object for the set's exterior roofs.
exposed_floor
A construction object for the set's exposed floors.
ground_wall
A construction object for the set's underground walls.
ground_roof
A construction object for the set's underground roofs.
ground_floor
A construction object for the set's ground-contact floors.
window
A construction object for apertures with an Outdoors boundary condition and a Wall face type for their parent face.
skylight
A construction object for apertures with an Outdoors boundary condition and a RoofCeiling or Floor face type for their parent face.
operable
A construction object for apertures with an Outdoors boundary condition and True is_operable property.
exterior_door
A construction object for opaque doors with an Outdoors boundary condition and a Wall face type for their parent face.
overhead_door
A construction object for opaque doors with an Outdoors boundary condition and a RoofCeiling or Floor face type for their parent face.
glass_door
A construction object for all glass doors with an Outdoors boundary condition.

Deconstruct ConstructionSet Interior

- [source code]

Deconstruct a construction set into its constituient interior constructions.

Inputs

constr_set [Required]
A construction set to be deconstructed. This can also be text for a construction set to be looked up in the construction set library.

Outputs

interior_wall
A construction object for the set's interior walls.
ceiling
A construction object for the set's interior roofs.
interior_floor
A construction object for the set's interior floors.
interior_window
A construction object for all apertures with a Surface boundary condition.
interior_door
A construction object for all opaque doors with a Surface boundary condition.
int_glass_door
A construction object for all glass doors with a Surface boundary condition.

Deconstruct Material

- [source code]

Deconstruct a material into its constituient attributes and values.

Inputs

mat [Required]
A material to be deconstructed. This can also be text for a material to be looked up in the material library.

Outputs

values
List of values for the attributes that define the material.
attr_names
List of text that is the same length as the values, which notes the attribute name for each value.
r_val_si
R-value of the material in m2-K/W. Note that R-values do NOT include the resistance of air films on either side of the material.
r_val_ip
R-value of the material in h-ft2-F/Btu. Note that R-values do NOT include the resistance of air films on either side of the material.

Apply ConstructionSet

- [source code]

Apply ConstructionSet to Honeybee Rooms or a Model.

Inputs

rooms [Required]

Honeybee Rooms to which the input _constr_set should be assigned. This can also be a Honeybee Model for which all Rooms will be assigned the ConstructionSet.

constr_set [Required]

A Honeybee ConstructionSet to be applied to the input _room. This can also be text for a construction set to be looked up in the construction set library.

Outputs

rooms

The input Rooms with their construction sets edited.

Apply Opaque Construction

- [source code]

Apply OpaqueConstruction to Honeybee Faces, Doors or Room walls.

This component supports the assigning of different constructions based on cardinal orientation, provided that a list of OpaqueConstructions are input to the _constr.

Inputs

hb_objs [Required]

Honeybee Faces, Doors, Rooms or a Model to which the input _constr should be assigned. For the case of a Room or a Model, the construction will only be applied to the Room's outdoor walls. Note that, if you need to assign a construction to all the roofs, floors, etc. of a Room, the best practice is to create a ConstructionSet and assing that to the Room.

constr [Required]

A Honeybee OpaqueConstruction to be applied to the input _hb_objs. This can also be text for a construction to be looked up in the opaque 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.

Outputs

hb_objs

The input honeybee objects with their constructions edited.

Apply Shade Construction

- [source code]

Apply a ShadeConstruction to Honeybee Shade objects. Alternatively, it can assign a ShadeConstruction to all of the child shades of an Aperture, Door, Face, or a Room.

This component supports the assigning of different constructions based on cardinal orientation, provided that a list of ShadeConstructions are input to the _constr.

Inputs

hb_objs [Required]
Honeybee Shades, Apertures, Doors, Faces, or Rooms to which the input _constr should be assigned. For the case of a Honeybee Aperture, Door, Face or Room, the ShadeConstruction will be assigned to only the child shades directly assigned to that object. So passing in a Room will not change the construction of shades assigned to Apertures of the Room's Faces. If this is the desired outcome, then the Room should be deconstructed into its child objects before using this component.
constr [Required]
A 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.

Outputs

hb_objs
The input honeybee objects with their constructions edited.

Apply Window Construction

- [source code]

Apply WindowConstruction or WindowConstructionShade to Honeybee Apertures or glass Doors. Alternatively, it can assign WindowConstructions to the child apertures of input Faces or the apertures within Room walls.

This component supports the assigning of different constructions based on cardinal orientation, provided that a list of WindowConstructions are input to the _constr.

Inputs

hb_objs [Required]

Honeybee Apertures, Faces, Doors, Rooms or a Model to which the input _constr should be assigned. For the case of a Room or a Model, the construction will only be applied to the apertures in the the Room's outdoor walls. Note that, if you need to assign a construction to all the skylights, glass doors, etc. of a Room, the best practice is to create a ConstructionSet and assing that to the Room.

constr [Required]

A Honeybee WindowConstruction or WindowConstructionShade to be applied to the input _hb_objs. This can also be text for a construction to be looked up in the window 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.

Outputs

hb_objs

The input honeybee objects with their constructions edited.

Opaque Construction

- [source code]

Create an EnergyPlus opaque construction. Material inputs can be either the identifiers of materials within the library or a custom material made with any of the EnergyPlus Material components.

Note that the _materials should be ordered from outermost (exterior) layer to the innermost (interior) layer.

Inputs

name
Text to set the name for the Construction and to be incorporated into a unique Construction identifier.
materials [Required]
List of materials in the construction (from exterior to interior). These materials can be either fully-detailed material objects built with the material components or text for a material identifier to be looked up in the opaque material library. Note that a native Grasshopper "Merge" component can be used to help order the materials correctly for the input here.

Outputs

constr
An opaque construction that can be assigned to Honeybee Faces or ConstructionSets.

Shade Construction

- [source code]

Create an EnergyPlus shade construction. Note that Shade objects in EnergyPlus do not have layers and are only defined by their exterior reflectance.

Inputs

name
Text to set the name for the Construction and to be incorporated into a unique Construction identifier.
sol_ref
A number between 0 and 1 for the solar reflectance of the construction. Default: 0.2.
vis_ref
A number between 0 and 1 for the visible reflectance of the construction. Default: 0.2.
specular
A boolean to note whether the reflection off the shade should be diffuse (False) or specular (True). Set to True if the construction is representing a glass facade or a mirror material. Default: False.

Outputs

constr
A shade construction that can be assigned to Honeybee Shades or ConstructionSets.

Window Construction

Create an EnergyPlus window construction. Material inputs can be either the identifiers of materials within the library or a custom material made with any of the EnergyPlus Material components.

Note that the _materials should be ordered from outermost (exterior) layer to the innermost (interior) layer.

Inputs

name

Text to set the name for the Construction and to be incorporated into a unique Construction identifier.

materials [Required]

List of materials in the construction (from exterior to interior). These materials can be either fully-detailed material objects built with the material components or text for a material identifier to be looked up in the window material library. Note that a native Grasshopper "Merge" component can be used to help order the materials correctly for the input here.

frame

An optional window frame material to denote the frame that surrounds the window construction. Frame materials can be created using the "HB Window Frame" component.

Outputs

constr

A window construction that can be assigned to Honeybee Apertures or ConstructionSets.

Window Construction Shade

Create an EnergyPlus window construction that includes shades/blinds or a dynamically- controlled glass pane.

The result can be assigned to any Aperture or ConstructionSet just like any other WindowConstruction.

Inputs

name
Text to set the name for the Construction and to be incorporated into a unique Construction identifier.
win_constr [Required]
A WindowConstruction object that serves as the "switched off" version of the construction (aka. the "bare construction"). The shade material and shade location will be used to modify this starting construction. This can also be text for a construction identifier to be looked up in the window construction library.
shd_material [Required]
An Shade Material or an Blind Material that serves as the shading layer for this construction. This can also be a Glass Material, which will indicate that the WindowConstruction has a dynamically- controlled glass pane like an electrochromic window assembly. This can also be text for a material identifier to be looked up in the window material library.
shd_location
Text to indicate where in the window assembly the shade material is located. (Default: "Interior"). Choose from the following 3 options:
- Interior
- Between
- ExteriorNote that the WindowConstruction must have at least one gas gap to use the "Between" option. Also note that, for a WindowConstruction with more than one gas gap, the "Between" option defalts to using the inner gap as this is the only option that EnergyPlus supports.
control_type
An integer or text to indicate how the shading device is controlled, which determines when the shading is “on” or “off.” (Default: "AlwaysOn"). Choose from the options below (units for the values of the corresponding setpoint are noted in parentheses next to each option): 0 = AlwaysOn 1 = OnIfHighSolarOnWindow (W/m2) 2 = OnIfHighHorizontalSolar (W/m2) 3 = OnIfHighOutdoorAirTemperature (C) 4 = OnIfHighZoneAirTemperature (C) 5 = OnIfHighZoneCooling (W) 6 = OnNightIfLowOutdoorTempAndOffDay (C) 7 = OnNightIfLowInsideTempAndOffDay (C) 8 = OnNightIfHeatingAndOffDay (W)
setpoint
A number that corresponds to the specified control_type. This can be a value in (W/m2), (C) or (W) depending upon the control type.
schedule
An optional ScheduleRuleset or ScheduleFixedInterval to be applied on top of the control type. If None, the control type will govern all behavior of the construction.

Outputs

constr
A shaded window construction that can be assigned to Honeybee Apertures or ConstructionSets.

Opaque Material

- [source code]

Create a standard opaque material, which can be plugged into the "HB Opaque Construction" component.

Inputs

name
Text to set the name for the material and to be incorporated into a unique material identifier.
thickness [Required]
Number for the thickness of the material layer [m].
conductivity [Required]
Number for the thermal conductivity of the material [W/m-K].
density [Required]
Number for the density of the material [kg/m3].
spec_heat [Required]
Number for the specific heat of the material [J/kg-K].
roughness
Text describing the relative roughness of the material. Must be one of the following: 'VeryRough', 'Rough', 'MediumRough', 'MediumSmooth', 'Smooth', 'VerySmooth'. (Default: 'MediumRough').
therm_absp
A number between 0 and 1 for the fraction of incident long wavelength radiation that is absorbed by the material. (Default: 0.9).
sol_absp
A number between 0 and 1 for the fraction of incident solar radiation absorbed by the material. (Default: 0.7).
vis_absp
A number between 0 and 1 for the fraction of incident visible wavelength radiation absorbed by the material. Default value is the same as the sol_absp.

Outputs

mat
A standard opaque material that can be assigned to a Honeybee Opaque construction.

Opaque Material No Mass

Create an opaque material that has no mass, which can be plugged into the "HB Opaque Construction" component.

Inputs

name
Text to set the name for the material and to be incorporated into a unique material identifier.
r_value [Required]
Number for the R-value of the material [m2-K/W].
roughness
Text describing the relative roughness of a particular material. Must be one of the following: 'VeryRough', 'Rough', 'MediumRough', 'MediumSmooth', 'Smooth', 'VerySmooth'. (Default: 'MediumRough').
therm_absp
A number between 0 and 1 for the fraction of incident long wavelength radiation that is absorbed by the material. (Default: 0.9).
sol_absp
A number between 0 and 1 for the fraction of incident solar radiation absorbed by the material. (Default: 0.7).
vis_absp
A number between 0 and 1 for the fraction of incident visible wavelength radiation absorbed by the material. Default value is the same as the sol_absp.

Outputs

mat
A no-mass opaque material that can be assigned to a Honeybee Opaque construction.

Glass Material

- [source code]

Create a window material to describe a single glass pane corresponding to a layer in a window construction. This material can be plugged into the "HB Window Construction" component.

Inputs

name
Text to set the name for the material and to be incorporated into a unique material identifier.
thickness [Required]
Number for the thickness of the glass layer [m]. Typical values range from 0.003 meters (3 mm) to 0.012 meters (12 mm).
transmittance
Number between 0 and 1 for the transmittance of both solar radiation and visible light through the glass at normal incidence. (Default: 0.85 for clear uncoated glass).
reflectance
Number between 0 and 1 for the reflectance of both solar radiation and visible light off of the front side of the glass at normal incidence. (Default: 0.075 for clear uncoated glass).
t_infrared
Long-wave transmittance of the glass at normal incidence. (Default: 0).
emiss_front
Number between 0 and 1 for the infrared hemispherical emissivity of the front side of the glass. (Defaul: 0.84, which is typical of clear glass).
emiss_back
Number between 0 and 1 for the infrared hemispherical emissivity of the back side of the glass. (Default: 0.84, which is typical of clear glass).
conductivity
Number for the thermal conductivity of the glass in W/m-K. (Default: 0.9, whih is typical of clear glass).

Outputs

mat
A window material that describes a single glass pane and can be assigned to a Honeybee Window construction.

Shade Material

Create a material for a shade layer in a window construction (like a roller shade). This material can be plugged into the "HB Window Construction" component.

Reflectance and emissivity properties are assumed to be the same on both sides of the shade. Shades are considered to be perfect diffusers.

Inputs

name
Text to set the name for the material and to be incorporated into a unique material identifier.
thickness [Required]
Number for the thickness of the shade layer in meters.
transmittance
Number between 0 and 1 for the transmittance of both solar radiation and visible light through the shade. (Default: 0.4, which is typical of a white diffusing shade).
reflectance
Number between 0 and 1 for the reflectance of both solar radiation and visible light off of the shade. (Default: 0.5, which is typical of a white diffusing shade).
t_infrared
Long-wave hemisperical transmittance of the shade. (Default: 0).
emissivity
Number between 0 and 1 for the infrared hemispherical emissivity of the shade. (Default: 0.9, which is typical of most diffusing shade materials).
conductivity
Number for the thermal conductivity of the shade in W/m-K. (Default: 0.05, typical of cotton shades).
dist_to_glass
A number between 0.001 and 1.0 for the distance between the shade and neighboring glass layers [m]. (Default: 0.05 (50 mm)).
open_mult
Factor between 0 and 1 that is multiplied by the area at the top, bottom and sides of the shade for air flow calculations. (Default: 0.5).
permeability
The fraction of the shade surface that is open to air flow. Must be between 0 and 0.8. (Default: 0 for no permeability).

Outputs

mat
A material for a shade layer in a window construction (like a roller shade) that can be assigned to a Honeybee Window construction.

Window Frame

Create a window frame matrial that can be assigned to a Window Construction by plugging it into the frame_ input of the "HB Window Construction" component.

Inputs

name

Text to set the name for the material and to be incorporated into a unique material identifier.

width [Required]

Number for the width of frame in plane of window [m]. The frame width is assumed to be the same on all sides of window.

conductance [Required]

Number for the thermal conductance of the frame material measured from inside to outside of the frame surface (no air films) and taking 2D conduction effects into account [W/m2-K]. Values for typical frame materials are as follows.

edge_to_cent

Number between 0 and 4 for the ratio of the glass conductance near the frame (excluding air films) divided by the glass conductance at the center of the glazing (excluding air films). This is used only for multi-pane glazing constructions. This ratio should usually be greater than 1.0 since the spacer material that separates the glass panes is usually more conductive than the gap between panes. A value of 1 effectively indicates no spacer. Values should usually be obtained from the LBNL WINDOW program so that the unique characteristics of the window construction can be accounted for. (Default: 1).

outside_proj

Number for the distance that the frame projects outward from the outside face of the glazing [m]. This is used to calculate shadowing of frame onto glass, solar absorbed by the frame, IR emitted and absorbed by the frame, and convection from frame. (Default: 0).

inside_proj

Number for the distance that the frame projects inward from the inside face of the glazing [m]. This is used to calculate solar absorbed by the frame, IR emitted and absorbed by the frame, and convection from frame. (Default: 0).

therm_absp

A number between 0 and 1 for the fraction of incident long wavelength radiation that is absorbed by the material. (Default: 0.9).

sol_absp

A number between 0 and 1 for the fraction of incident solar radiation absorbed by the material. (Default: 0.7).

vis_absp

A number between 0 and 1 for the fraction of incident visible wavelength radiation absorbed by the material. Default value is the same as the sol_absp.

Outputs

frame

A window frame material that can be assigned to a Honeybee Window construction.

Window Material

- [source code]

Create a simple window material to describe an entire glazing system, including glass, gaps, and frame. This material can be plugged into the "HB Window Construction" component.

Inputs

name
Text to set the name for the material and to be incorporated into a unique material identifier.
u_factor [Required]
A number for the U-factor of the glazing system [W/m2-K] including standard air gap resistances on either side of the glazing system.
shgc [Required]
A number between 0 and 1 for the solar heat gain coefficient of the glazing system. This includes both directly transmitted solar heat as well as solar heat that is absorbed by the glazing system and conducts towards the interior.
t_vis
A number between 0 and 1 for the visible transmittance of the glazing system. (Default: 0.6).

Outputs

mat
A window material that describes an entire glazing system, including glass, gaps, and frame and can be assigned to a Honeybee Window construction.

Blind Material

- [source code]

Create a material for a blind layer in a window construction. This material can be plugged into the "HB Window Construction" component.

Window blind properties consist of flat, equally-spaced slats.

Inputs

name
Text to set the name for the material and to be incorporated into a unique material identifier.
vertical
Set to "True" to have the blinds be vertically-oriented and set to "False" to have them be horizontally-oriented. (Default: False for horizontal).
slat_width
The width of slat measured from edge to edge [m]. (Default: 0.025 m).
slat_separation
The distance between each of the slats [m]. (Default: 0.01875 m).
slat_thickness
A number between 0 and 0.1 for the thickness of the slat in meters. (Default: 0.001 m).
slat_angle
A number between 0 and 180 for the angle between the slats and the glazing normal in degrees. 90 signifies slats that are perpendicular to the glass. (Default: 45).
conductivity
Number for the thermal conductivity of the blind material [W/m-K]. (Default: 221, typical of aluminum blinds).
transmittance
Number between 0 and 1 for the transmittance of solar radiation and visible light through the blind material. (Default: 0).
reflectance
Number between 0 and 1 for the reflectance of solar radiation and visible light off of the blind material. (Default: 0.5, which is typical of a painted white blind).
t_infrared
Long-wave hemisperical transmittance of the blind material. (Default: 0).
emissivity
Number between 0 and 1 for the infrared hemispherical emissivity of the blind material. (Default: 0.9, which is typical of most painted blinds).
dist_to_glass
A number between 0.001 and 1.0 for the distance between the blind edge and neighboring glass layers [m]. (Default: 0.05 m).
open_mult
Factor between 0 and 1 that is multiplied by the area at the top, bottom and sides of the blind for air flow calculations. (Default: 0.5).

Outputs

mat
A material for a blind layer in a window construction that can be assigned to a Honeybee Window construction.

Custom Window Gap Material

- [source code]

Create a custom gas gap material that corresponds to a layer in a window construction. This material can be plugged into the "HB Window Construction" component.

This object allows you to specify specific values for conductivity, viscosity and specific heat through the following formula: property = A + (B * T) where: A, B = regression coefficients for the gas T = temperature [K]

Inputs

name
Text to set the name for the material and to be incorporated into a unique material identifier.
thickness [Required]
Number for the thickness of the gas gap layer in meters.
conductivity_a [Required]
First conductivity coefficient. Or condictivity in [W/m-K] if b coefficient is 0.
viscosity_a [Required]
First viscosity coefficient. Or viscosity in [kg/m-s] if b coefficient is 0.
specific_heat_a [Required]
First specific heat coefficient. Or the specific heat in [J/kg-K] if b coefficient is 0.
conductivity_b
Second conductivity coefficient. (Default: 0).
viscosity_b
Second viscosity coefficient. (Default: 0).
specific_heat_b
Second specific heat coefficient. (Default: 0).
spec_heat_ratio
A number for the the ratio of the specific heat a contant pressure, to the specific heat at constant volume. (Default: 1.0 for Air).
mol_weight
Number between 20 and 200 for the mass of 1 mol of the substance in grams. (Default: 20.0).

Outputs

mat
A custom gas gap material that describes a layer in a window construction and can be assigned to a Honeybee Window construction.

Vegetation Material

- [source code]

Create a vegetation material representing both plants and soil, which can be plugged into the "HB Opaque Construction" component.

Note that the underlying models for this material were developed using horizontal roofs and caution should be taken when applying ito to vertical walls.

Inputs

name

Text to set the name for the material and to be incorporated into a unique material identifier.

plant_height

A number between 0.005 and 1.0 for the height of plants in the vegetation layer [m]. (Default: 0.2 m).

leaf_area_ind

A number between 0.001 and 5.0 for the projected leaf area per unit area of soil surface (aka. Leaf Area Index or LAI). Note that the fraction of vegetation cover is calculated directly from LAI using an empirical relation. (Default: 1.0).

leaf_reflect

A number between 0.05 and 0.5 for the fraction of incident solar radiation that is reflected by the leaf surfaces. Solar radiation includes the visible spectrum as well as infrared and ultraviolet wavelengths. Typical values are 0.18 to 0.25. (Default: 0.22).

leaf_emiss

A number between 0.8 and 1.0 for the ratio of thermal radiation emitted from leaf surfaces to that emitted by an ideal black body at the same temperature. (Default: 0.95).

soil_reflect

A number between 0 and 1 for the fraction of incident solar radiation reflected by the soil material. (Default: 0.3).

soil_emiss

A number between 0 and 1 for the fraction of incident long wavelength radiation that is absorbed by the soil material. (Default: 0.9).

stomat_resist

A number between 50 and 300 for the resistance of the plants to moisture transport [s/m]. Plants with low values of stomatal resistance will result in higher evapotranspiration rates than plants with high resistance. (Default: 180).

thickness

Number for the thickness of the soil layer [m]. (Default: 0.1).

conductivity

Number for the thermal conductivity of the soil [W/m-K]. (Default: 0.35).

density

Number for the density of the soil [kg/m3]. (Default: 1100).

spec_heat

Number for the specific heat of the soil [J/kg-K]. (Default: 1200).

Outputs

mat

A vegetation material that can be assigned to a Honeybee Opaque construction.

Window Construction Dynamic

- [source code]

Create an EnergyPlus window construction with any number of dynamic states.

Inputs

name
Text to set the name for the Construction and to be incorporated into a unique Construction identifier.
constructions [Required]
List of materials in the construction (from exterior to interior). These materials can be either fully-detailed material objects built with the material components or text for a material identifier to be looked up in the window material library. Note that a native Grasshopper "Merge" component can be used to help order the materials correctly for the input here.
schedule [Required]
A control schedule that dictates which constructions that are active at given times throughout the simulation. Inputs can be either the identifiers of schedules within the library or custom schedules made with any of the honeybee schedule components. The values of the schedule should be intergers and range from 0 to one less then the number of constructions. Zero indicates that the first construction is active, one indicates that the second on is active, etc. The schedule type limits of this schedule should be "Control Level." If building custom schedule type limits that describe a particular range of states, the type limits should be "Discrete" and the unit type should be "Mode," "Control," or some other fractional unit.

Outputs

constr
A dynamic window construction that can be assigned to Honeybee Apertures or ConstructionSets.

Window Gap Material

- [source code]

Create a window gas gap material that corresponds to a layer in a window construction. This material can be plugged into the "HB Window Construction" component.

Inputs

name
Text to set the name for the material and to be incorporated into a unique material identifier.
thickness
Number for the thickness of the air gap layer in meters. (Default: 0.0125 m).
gas_types
A list of text describing the types of gas in the gap. Text must be one of the following: 'Air', 'Argon', 'Krypton', 'Xenon'.
gas_ratios
A list of text describing the volumetric fractions of gas types in the mixture. This list must align with the gas_types input list. Default: Equal amout of gases for each type.

Outputs

mat
A window gas gap material that describes a layer in a window construction and can be assigned to a Honeybee Window construction.

2 :: Schedules

Gene Pool to Day Schedule

- [source code]

Modify a native Grasshopper Gene Pool component into a format that makes it easy to input daily schedules into the other schedule components.

This essentially turns the Gene Pool into a list of 24 sliders representing an hourly timeseries over a day. Each slider runs from the low_bound to high_bound.

Inputs

gene_pool [Required]
The output of a native Grasshopper Gene Pool component.
template
An integer for the template for which the values of the gene pool will be set. Default: 0. Choose one of the templates:
0 - maximum values from 9:00 to 17:00 1 - minimum values from 9:00 to 17:00 2 - maximum values from 7:00 to 22:00 3 - minimum values from 7:00 to 22:00 4 - maximum values from 0:00 to 24:00 5 - minimum values from 0:00 to 24:00
low_bound
A number for the lower boundary of the schedule values.
up_bound
A number for the upper boundary of the schedule range.
decimals
An integer greater than or equal to 0 for the number of decimal places to use in each slider. Default: 1.
run [Required]
Set to "True" to run the component and modify the connected gene pool. Note that you on't be able to edit a connected gene pool while this input is set to "True".

Outputs

report
Reports, errors, warnings, etc.

Search Schedules

- [source code]

Search for available Schedules within the honeybee energy standards library.

Inputs

keywords
Optional keywords to be used to narrow down the output list of scheduless. If nothing is input here, all available schedules will be output.
join_words
If False or None, this component will automatically split any strings of multiple keywords (spearated by spaces) into separate keywords for searching. This results in a greater liklihood of finding an item in the search but it may not be appropropriate for all cases. You may want to set it to True when you are searching for a specific phrase that includes spaces. Default: False.

Outputs

schedules
A list of Schedules within the honeybee energy standards library (filtered by keywords_ if they are input).
type_limits
A list of all ScheduleTypeLimits within the honeybee energy standards library.

Deconstruct Schedule

- [source code]

Deconstruct a ScheduleRuleset into an array of day-long ladybug DataCollections representing each unique ScheduleDay that defines the ScheduleRuleset.

These DataCollections can be used to make visualizations of timeseries schedule values over each unique day of the schedule using a component like the "LB Line Chart".

Inputs

schedule [Required]
A ScheduleRuleSet to be deconstructed into DataCollections of timeseries schedule values for each unique day. This can also be the identifier of a Schedule to be looked up in the schedule library.
timestep
An integer for the number of steps per hour at which to make the resulting daily DataCollections.

Outputs

day_names
A list of display names for each unique ScheduleDay that defines the input ScheduleRuleset.
day_data
A list of day-long ladybug DataCollections representing each unique ScheduleDay that defines the ScheduleRuleset. These can be used to make visualizations of timeseries schedule values over each day of the schedule using a component like the "LB Line Chart".
type_limit
The ScheduleTypeLimit object assigned to the ScheduleRuleset.

Schedule to Data

Get a ladybug DataCollection representing this schedule at a given timestep.

This DataCollection can be used to visualize timeseries schedule values over the entire period of a simulation using a component like the "LB Hourly Plot".

This DataCollection can also be used in the crafting of conditional statements with the ladybug components. For example, making a psychrometric chart of zone temperature/humidity for only the hours that the occupancy schedule is above a certain threshold.

Inputs

schedule [Required]
A ScheduleRuleSet or SchedileFixedInterval for which a DataCollection of timeseries schedule values will be produced. This can also be the identifier of a Schedule to be looked up in the schedule library.
analysis_period
An optional AnalysisPeriod to set the start and end datetimes of the resulting DataCollection. The timestep of this AnalysisPeriod will also be used to determine the timestep of the resulting DataCollection.
week_start_day
An optional text string to set the start day of the week of the schedule timeseries data. Default: Sunday. Choose from the following:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
holidays
An optional list of strings (eq: 25 Dec) to represent the holidays in the resulting timeseries. Holiday schedules will be used for these dates in the resulting timeseries.

Outputs

data
A ladybug DataCollection representing the timeseries values of the schedule. This can be used to visualize timeseries schedule values over the entire period of a simulation using a component like the "LB Hourly Plot".

Apply Room Schedules

- [source code]

Apply schedules to a Room, Model or ProgramType.

Note that, if a schedule is assigned to a Room or ProgramType that posseses no value for a given load, an error will be raised. For example, assigning a gas_equip_sch_ to a Room that has no GasEquipment object associated with it. This situation can be avoided by first passing the Rooms or ProgramTypes through the "HB Apply Load Values" component to eastablish a value for a given load.

Inputs

room_or_program [Required]

Honeybee Rooms or Honeybee ProgramType objects for which schedules should be changed. This can also be the identifier of a ProgramType to be looked up in the program type library. This can also be a Honeybee Model for which all Rooms will be assigned the schedules.

occupancy_sch

A fractional schedule for the occupancy over the course of the year. This can also be the identifier of a schedule to be looked up in the schedule library.

activity_sch

A schedule for the activity of the occupants over the course of the year. The type limt of this schedule should be "ActivityLevel" and the values of the schedule equal to the number of Watts given off by an individual person in the room. If None, it will a default constant schedule with 120 Watts per person will be used, which is typical of awake, adult humans who are seated.

lighting_sch

A fractional schedule for the use of lights over the course of the year. This can also be the identifier of a schedule to be looked up in the schedule library.

electric_equip_sch

A fractional schedule for the use of electric equipment over the course of the year. This can also be the identifier of a schedule to be looked up in the schedule library.

gas_equip_sch

A fractional schedule for the use of gas equipment over the course of the year. This can also be the identifier of a schedule to be looked up in the schedule library.

hot_water_sch

A fractional schedule for the use of service hot water over the course of the year. This can also be the identifier of a schedule to be looked up in the schedule library.

infiltration_sch

A fractional schedule for the infiltration over the course of the year. This can also be the identifier of a schedule to be looked up in the schedule library.

ventilation_sch

A fractional schedule for the ventilation over the course of the year. This can also be the identifier of a schedule to be looked up in the schedule library. The fractional values will get multiplied by the total design flow rate to yield a complete ventilation profile. Setting this schedule to be the occupancy schedule of the zone will mimic demand controlled ventilation.

heating_setpt_sch

A temperature schedule for the heating setpoint. This can also be a identifier of a schedule to be looked up in the schedule library. The type limit of this schedule should be temperature and the values should be the temperature setpoint in degrees Celcius.

cooling_setpt_sch

A temperature schedule for the cooling setpoint. This can also be a identifier of a schedule to be looked up in the schedule library. The type limit of this schedule should be temperature and the values should be the temperature setpoint in degrees Celcius.

Outputs

report

Reports, errors, warnings, etc.

mod_obj

The input Rooms or ProgramTypes with their schedules modified.

Apply Shade Schedule

- [source code]

Apply a transmittance schedule to Honeybee Shade objects. Alternatively, it can assign a transmittance schedule to all of the child shades of an Aperture, Door, Face, or a Room.

This component supports the assigning of different schedules based on cardinal orientation, provided that a list of transmittance schedule are input to the _trans_sch.

Inputs

hb_objs [Required]

Honeybee Shades, Apertures, Door, Faces, Rooms or a Model to which the input _trans_sch should be assigned. For the case of a Honeybee Aperture, Door, Face, Room, or Model, the ShadeConstruction will be assigned to only the child shades directly assigned to that object. So passing in a Room will not change the schedule of shades assigned to Apertures of the Room's Faces. If changing these sub-children is the desired outcome, then the Room should be deconstructed into its child objects before using this component.

trans_sch [Required]

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

Outputs

hb_objs

The input honeybee objects with their shade transmittance schedules edited.

Constant Schedule

Create a schedule from a single constant value or a list of 24 hourly values repeating continuously over every day of the year.

Inputs

values [Required]
A list of 24 values that represent the schedule values at each hour of the day. This can also be a single constant value for the whole day.
name
Text to set the name for the Schedule and to be incorporated into a unique Schedule identifier.
type_limit
A text string from the identifier of the ScheduleTypeLimit to be looked up in the schedule type limit library. This can also be a custom ScheduleTypeLimit object from the "HB Type Limit" component. The input here will be used to validate schedule values against upper/lower limits and assign units to the schedule values. Default: "Fractional" for values that range continuously between 0 and 1. Choose from the following built-in options:
- Fractional
- On-Off
- Temperature
- Activity Level
- Power
- Humidity
- Angle
- Delta Temperature
- Control Level

Outputs

report
Reports, errors, warnings, etc.
schedule
A ScheduleRuleset object that can be assigned to a Room, a Load object, or a ProgramType object.
idf_text
Text strings for the EnergyPlus Schedule that will ultimately be written into the IDF for simulation. This can also be used to add the schedule to the schedule library that is loaded up upon the start of Honeybee by copying this text into the honeybee/library/schedules/ user_library.idf file.

Fixed Interval Schedule

Create a schedule defined by a list of values at a fixed interval or timestep running over the entirety of the simulation period.

Inputs

values [Required]
A list of timeseries values occuring at a fixed timestep over the entire simulation. Typically, this should be a list of 8760 values for each hour of the year but it can be a shorter list if you don't plan on using the schedule in an annual simulation. In this case, the analysisperiod should probably be different than the default. This list can also have a length much greater than 8760 if a timestep greater than 1 is used.
timestep
An integer for the number of steps per hour that the input values correspond to. For example, if each value represents 30 minutes, the timestep is 2. For 15 minutes, it is 4. Default is 1, meaning each value represents a single hour. Must be one of the
analysis_period
A ladybug AnalysisPeriod object to note when the input values take effect. Default is for the whole year. Note that this default usually should not be changed unless you plan to run a simulation that is much shorter than a year.
name
Text to set the name for the Schedule and to be incorporated into a unique Schedule identifier.
type_limit
A text string from the name of the ScheduleTypeLimit to be looked up in the schedule type limit library. This can also be a custom ScheduleTypeLimit object from the "HB Type Limit" component. The input here will be used to validate schedule values against upper/lower limits and assign units to the schedule values. Default: "Fractional" for values that range continuously between 0 and 1. Choose from the following built-in options:
- Fractional
- On-Off
- Temperature
- Activity Level
- Power
- Humidity
- Angle
- Delta Temperature
- Control Level

Outputs

report
Reports, errors, warnings, etc.
schedule
A ScheduleRuleset object that can be assigned to a Room, a Load object, or a ProgramType object.

Seasonal Schedule

- [source code]

Create a schedule using from other ScheduleRulesets and AnalysisPeriods over which each schedule should be applied.

Inputs

base_schedule [Required]

A ScheduleRuleset that represents the base schedule on top of which the other _season_scheds will be applied. This can also be text to look up a ScheduleRuleset in the schedule library. Any time period that is not covered by the input _analysis_periods will default to this schedule. Furthermore, the summer and winter design day schedules will be taken from this schedule as well as the ScheduleTypeLimits.

season_scheds [Required]

A list of ScheduleRulesets that align with the _analysis_periods below and represent the schedules that will be applied over the _base_schedule for the duration of the respective AnalysisPeriod. This can also be text to look up ScheduleRulesets in the schedule library.

analysis_periods [Required]

A list of AnalysusPeriod objects that align with the _season_scheds and represent the time periods over which each season schedule should be applied. Note that, if these AnalysisPeriods overlap with one another, then the schedules that come later in this list will overwrite those that come earlier in the list for the duration of the overlapping time period.

summer_des

An optional list of 24 values that represent the schedule values at each hour of the summer design day. This can also be a single constant value for the whole day. If None, the summer design day schedule of the _base_schedule will be used.

winter_des

name

Text to set the name for the Schedule and to be incorporated into a unique Schedule identifier.

Outputs

out

Reports, errors, warnings, etc.

schedule

A ScheduleRuleset object that can be assigned to a Room, a Load object, or a ProgramType object.

idf_year

Text string for the EnergyPlus ScheduleYear that will ultimately be written into the IDF for simulation. This can also be used to add the schedule to the schedule library that is loaded up upon the start of Honeybee by copying this text into the honeybee/library/schedules/ user_library.idf file along with the other idf text outputs.

idf_week

Text string for the EnergyPlus ScheduleWeek that will ultimately be written into the IDF for simulation. This can also be used to add the schedule to the schedule library that is loaded up upon the start of Honeybee by copying this text into the honeybee/library/schedules/ user_library.idf file along with the other idf text outputs.

idf_days

Text strings for the EnergyPlus SchedulDays that will ultimately be written into the IDF for simulation. This can also be used to add the schedule to the schedule library that is loaded up upon the start of Honeybee by copying this text into the honeybee/library/schedules/ user_library.idf file along with the other idf text outputs.

Type Limit

Create a custom ScheduleTypeLimit object that can be assigned to any schedule object.

Schedule types exist for the sole purpose of validating schedule values against upper/lower limits and assigning a data type and units to the schedule values. As such, they are not necessary to run energy simulations but their use is generally considered good practice.

Inputs

name [Required]
Text to set the name for the ScheduleTypeLimit. This should be unique to avoif conflcit with other schedule types.
low_limit
An optional number for the lower limit for values in the schedule. If None, there will be no lower limit.
up_limit
An optional number for the upper limit for values in the schedule. If None, there will be no upper limit.
discrete
Boolean to not whether the values of the schedule are continuous or discrete. The latter means that only integers are accepted as schedule values. Default: False for 'Continuous'.
unit_type
Text for an EnergyPlus unit type, which will be used to assign units to the values in the schedule. Note that this field is not used in the actual calculations of EnergyPlus. Default: 'Dimensionless'. Choose from the following:
- Dimensionless
- Temperature
- DeltaTemperature
- PrecipitationRate
- Angle
- ConvectionCoefficient
- ActivityLevel
- Velocity
- Capacity
- Power
- Availability
- Percent
- Control
- Mode

Outputs

report
Reports, errors, warnings, etc.
type_limit
A ScheduleTypeLimit object that can be assigned to any schedule object.

3 :: Loads

Apply ProgramType

- [source code]

Apply ProgramType objects to Rooms or a Model.

Inputs

rooms [Required]

Honeybee Rooms to which the input program should be assigned. This can also be a Honeybee Model for which all Rooms will be assigned the ProgramType.

program [Required]

A ProgramType object to apply to the input rooms. This can also be 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.

overwrite

A Boolean to note whether any loads assigned specifically to the Room, which overwrite the loads of ProgramType should be reset so that they are determined by the input program. (Default: False).

Outputs

report

Reports, errors, warnings, etc.

rooms

The input Rooms with their loads edited.

Deconstruct ProgramType

- [source code]

Deconstruct a ProgramType object into its component load objects.

Inputs

program [Required]
A ProgramType object or text for the identifier of a ProgramType to be looked up in the program type library.

Outputs

people
A People object that describes the occupancy of the program. If None, no people are assumed to occupy the program.
lighting
A Lighting object that describes the lighting usage of the program. If None, no lights are assumed to be installed.
electric_equip
An ElectricEquipment object to describe the usage of electric equipment within the program. If None, no electric equipment is assumed to be installed.
gas_equip
A GasEquipment object to describe the usage of gas equipment within the program. If None, no gas equipment is assumed to be installed.
hot_water
A ServiceHotWater object to describe the usage of hot water within the program. If None, no hot water is be assumed for the program.
infiltration
An Infiltration object to describe the outdoor air leakage of the program. If None, no infiltration is be assumed for the program.
ventilation
A Ventilation object to describe the minimum outdoor air requirement of the program. If None, no ventilation requirement is be assumed for the program.
setpoint
A Setpoint object to describe the temperature and humidity setpoints of the program. If None, the ProgramType cannot be assigned to a Room that is conditioned.

Apply Absolute Load Values

Apply absolute load values to Rooms.

Note that, while the assigned load values are absolute, this component will convert them to the "normalized" value for each room (eg. lighting per floor area) in order to apply them to the rooms. So any existing specification of load intensity is overwritten with the absolute load here.

This also means that, if a room has no floors (or exterior walls for infiltration), the resulting load values will be equal to 0 regardless of the input here. The only exception is the vent_flow_, which will be applied regardless of the room properties.

This component will not edit any of the schedules or other properties associated with each load value. If no schedule currently exists to describe how the load varies over the simulation, the "Always On" schedule will be used as a default.

Inputs

rooms [Required]

Honeybee Rooms to which the input load values should be assigned. This can also be a Honeybee Model for which all Rooms will be assigned the loads.

person_count

A number for the quantity of people in the room.

lighting_watts

A number for the installed wattage of lighting in the room (W).

electric_watts

A number for the installed wattage of electric equipment in the room (W).

gas_watts

A number for the installed wattage of gas equipment in the room (W).

hot_wtr_flow

Number for the peak flow rate of service hot water in the room in liters per hour (L/h).

infiltration_ach

A number for the infiltration flow rate in air changes per hour (ACH).

vent_flow

A numerical value for the absolute of flow of outdoor air ventilation for the room in cubic meters per second (m3/s). Note that inputting a value here will overwrite all specification of outdoor air ventilation currently on the room (per_floor, per_person, ach).

Outputs

report

Reports, errors, warnings, etc.

rooms

The input Rooms with their load values modified.

Apply Daylight Control

- [source code]

Apply simple daylight controls to Rooms.

Such simple controls will dim the lights in the energy simulation according to whether the illuminance at a sensor location is at a target illuminance setpoint. The method used to estimate illuiminance is fairly simple and, for more detailed control over the parameters used to compute illuminance, the "HB Daylight Control Schedule" component under HB-Radiance should be used.

Inputs

rooms [Required]

Honeybee Rooms to which simple daylight controls should be assigned. This can also be a Honeybee Model for which all Rooms will be assigned daylight control sensors.

sensor_points

A list of point objects that align with the input _rooms and assign the position of the daylight sensor within the Room. This point should lie within the Room volume and a warning will be thrown and no daylight controls assigned for any point that lies outside the corresponding room. If unspecified, the sensor will be assigned to the center of the room at 0.8 meters above the floor. Note that such a center point might lie outside rooms that are significantly concave and no daylight controls will be assigned to these rooms in this case.

ill_setpoint

A number for the illuminance setpoint in lux beyond which electric lights are dimmed if there is sufficient daylight. Some common setpoints are listed below. (Default: 300 lux). 50 lux - Corridors and hallways. 150 lux - Computer work spaces (screens provide illumination). 300 lux - Paper work spaces (reading from surfaces that need illumination). 500 lux - Retail spaces or museums illuminating merchandise/artifacts. 1000 lux - Operating rooms and workshops where light is needed for safety.

control_fract

A number between 0 and 1 that represents the fraction of the Room lights that are dimmed when the illuminance at the sensor position is at the specified illuminance. 1 indicates that all lights are dim-able while 0 indicates that no lights are dim-able. Deeper rooms should have lower control fractions to account for the face that the lights in the back of the space do not dim in response to suitable daylight at the front of the room. (Default: 1).

min_power_in

A number between 0 and 1 for the the lowest power the lighting system can dim down to, expressed as a fraction of maximum input power. (Default: 0.3).

min_light_out

A number between 0 and 1 the lowest lighting output the lighting system can dim down to, expressed as a fraction of maximum light output. (Default: 0.2).

off_at_min

Boolean to note whether lights should switch off completely when they get to the minimum power input. (Default: False).

Outputs

report

Reports, errors, warnings, etc.

rooms

The input Rooms with simple daylight controls assigned to them.

Apply Load Values

Apply or edit load values on a Room or ProgramType.

This component will not edit any of the schedule objects associated with each load value. If no schedule currently exists to describe how the load varies over the simulation, the "Always On" schedule will be used as a default.

Inputs

room_or_program [Required]

Honeybee Rooms or ProgramType objects to which the input load objects should be assigned. This can also be the identifier of a ProgramType to be looked up in the program type library. This can also be a Honeybee Model for which all Rooms will be assigned the loads.

people_per_floor

A numerical value for the number of people per square meter of floor area.

lighting_per_floor

A numerical value for the lighting power density in Watts per square meter of floor area.

electric_per_floor

A numerical value for the electric equipment power density in Watts per square meter of floor area.

gas_per_floor

A numerical value for the gas equipment power density in Watts per square meter of floor area.

hot_wtr_per_floor

A numerical value for the total volume flow rate of water per unit area of floor in (L/h-m2).

infilt_per_exterior

A numerical value for the intensity of infiltration in m3/s per square meter of exterior surface area. Typical values for this property are as follows (note all values are at typical building pressures of ~4 Pa):

vent_per_floor

A numerical value for the intensity of outdoor air ventilation in m3/s per square meter of floor area. This will be added to the vent_per_person_ and vent_ach_ to produce the final minimum outdoor air specification.

vent_per_person

A numerical value for the intensity of outdoor air ventilation in m3/s per person. This will be added to the vent_per_floor_, and vent_ach_ to produce the final minimum outdoor air specification. Note that setting this value does not mean that ventilation is varied based on real-time occupancy but rather that the minimum level of ventilation is determined using this value and the People object of the zone. To vary ventilation on a timestep basis, a ventilation schedule should be used or the dcv_ option should be selected on the HVAC system if it is available.

vent_ach

A numerical value for the intensity of outdoor air ventilation in air changes er hour (ACH). This will be added to the vent_per_floor_ and vent_per_person_ to produce the final minimum outdoor air specification.

Outputs

report

Reports, errors, warnings, etc.

mod_obj

The input Rooms or ProgramTypes with their load values modified.

Apply Setpoint Values

- [source code]

Apply values for setpoints to a Room or ProgramType.

Inputs

room_or_program [Required]

Honeybee Rooms or ProgramType objects to which the input setpoints should be assigned. This can also be the identifier of a ProgramType to be looked up in the program type library. This can also be a Honeybee Model for which all Rooms will be assigned the setpoints.

cooling_setpt

A numerical value for a single constant temperature for the cooling setpoint [C].

heating_setpt

A numerical value for a single constant temperature for the heating setpoint [C].

humid_setpt

A numerical value for a single constant value for the humidifying setpoint [%].

dehumid_setpt

A numerical value for a single constant value for the dehumidifying setpoint [%].

cutout_difference

An optional positive number for the temperature difference between the cutout temperature and the setpoint temperature. Specifying a non-zero number here is useful for modeling the throttling range associated with a given setup of setpoint controls and HVAC equipment. Throttling ranges describe the range where a zone is slightly over-cooled or over-heated beyond the thermostat setpoint. They are used to avoid situations where HVAC systems turn on only to turn off a few minutes later, thereby wearing out the parts of mechanical systems faster. They can have a minor impact on energy consumption and can often have significant impacts on occupant thermal comfort, though using the default value of zero will often yield results that are close enough when trying to estimate the annual heating/cooling energy use. Specifying a value of zero effectively assumes that the system will turn on whenever conditions are outside the setpoint range and will cut out as soon as the setpoint is reached. (Default: 0).

Outputs

report

Reports, errors, warnings, etc.

mod_obj

The input Rooms or ProgramTypes with their setpoint values edited.

Equipment

- [source code]

Create an Equipment object that can be used to specify equipment usage in a ProgramType.

Inputs

name
Text to set the name for the Equipment and to be incorporated into a unique Equipment identifier. If None, a unique name will be generated.
watts_per_area [Required]
A numerical value for the equipment power density in Watts per square meter of floor area.
schedule [Required]
A fractional schedule for the use of equipment over the course of the year. The fractional values will get multiplied by the _watts_per_area to yield a complete equipment profile.
radiant_fract
A number between 0 and 1 for the fraction of the total equipment load given off as long wave radiant heat. (Default: 0).
latent_fract
A number between 0 and 1 for the fraction of the total equipment load that is latent (as opposed to sensible). (Default: 0).
lost_fract
A number between 0 and 1 for the fraction of the total equipment load that is lost outside of the zone and the HVAC system. Typically, this is used to represent heat that is exhausted directly out of a zone (as you would for a stove). (Default: 0).
gas
Set to "True" to have the output Equipment object be for GasEquipment (as opposed to ElectricEquipment).

Outputs

equip
An Equipment object that can be used to specify equipment usage in a ProgramType.

Infiltration

Create an Infiltration object that can be used to create a ProgramType or be assigned directly to a Room.

Inputs

name
Text to set the name for the Infiltration and to be incorporated into a unique Infiltration identifier. If None, a unique name will be generated.
flow_per_ext_area [Required]
A numerical value for the intensity of infiltration in m3/s per square meter of exterior surface area. Typical values for this property are as follows (note all values are at typical building pressures of ~4 Pa):
- 0.0001 (m3/s per m2 facade) - Tight building
- 0.0003 (m3/s per m2 facade) - Average building
- 0.0006 (m3/s per m2 facade) - Leaky building
schedule
A fractional schedule for the infiltration over the course of the year. The fractional values will get multiplied by the flow_per_exterior_area to yield a complete infiltration profile.

Outputs

infil
An Infiltration object that can be used to create a ProgramType or be assigned directly to a Room.

Lighting

- [source code]

Create a Lighting object that can be used to create a ProgramType or be assigned directly to a Room.

Inputs

name
Text to set the name for the Lighting and to be incorporated into a unique Lighting identifier. If None, a unique name will be generated.
watts_per_area [Required]
A numerical value for the lighting power density in Watts per square meter of floor area.
schedule [Required]
A fractional for the use of lights over the course of the year. The fractional values will get multiplied by the _watts_per_area to yield a complete lighting profile.
radiant_fract
A number between 0 and 1 for the fraction of the total lighting load given off as long wave radiant heat.
visible_fract
A number between 0 and 1 for the fraction of the total lighting load given off as short wave visible light.
return_fract
A number between 0 and 1 for the fraction of the total lighting load that goes into the zone return air (into the zone outlet node). Default: 0.0 (representative of pendant lighting).
baseline
An optional number for the baseline lighting power density in W/m2 of floor area. This baseline is useful to track how much better the installed lights are in comparison to a standard like ASHRAE 90.1. If set to None, it will default to 11.84029 W/m2, which is that ASHRAE 90.1-2004 baseline for an office.

Outputs

lighting
A Lighting object that can be used to create a ProgramType or be assigned directly to a Room.

Process Load

- [source code]

Apply process loads to Rooms.

Examples of process loads include wood burning fireplaces, kilns, manufacturing equipment, and various industrial processes. They can also be used to represent certain specialized pieces of equipment to be separated from the other end uses, such as MRI machines, theatrical lighting, elevators, etc.

Inputs

rooms [Required]

Honeybee Rooms to which process loads should be assigned.

name

Text to set the name for the Process load and to be incorporated into a unique Process load identifier. If None, a unique name will be generated.

watts [Required]

A number for the process load power in Watts.

schedule [Required]

A fractional schedule for the use of the process over the course of the year. The fractional values will get multiplied by the _watts to yield a complete process load profile.

fuel_type [Required]

Text to denote the type of fuel consumed by the process. Using the "None" type indicates that no end uses will be associated with the process, only the zone gains. Choose from the following.

* Electricity

* NaturalGas

* Propane

* FuelOilNo1

* FuelOilNo2

* Diesel

* Gasoline

* Coal

* Steam

* DistrictHeating

* DistrictCooling

* OtherFuel1

* OtherFuel2

* None

use_category

Text to indicate the end-use subcategory, which will identify the process load in the EUI output. For example, “Cooking”, “Clothes Drying”, etc. (Default: General).

radiant_fract

A number between 0 and 1 for the fraction of the total process load given off as long wave radiant heat. (Default: 0).

latent_fract

A number between 0 and 1 for the fraction of the total process load that is latent (as opposed to sensible). (Default: 0).

lost_fract

A number between 0 and 1 for the fraction of the total process load that is lost outside of the zone and the HVAC system. Typically, this is used to represent heat that is exhausted directly out of a zone (as you would for a stove). (Default: 0).

Outputs

report

Reports, errors, warnings, etc.

rooms

The input Rooms with process loads assigned to them.

Service Hot Water

- [source code]

Create an ServiceHotWater object that can be used to specify hot water usage in a ProgramType.

Inputs

name
Text to set the name for the ServiceHotWater and to be incorporated into a unique ServiceHotWater identifier. If None, a unique name will be generated.
flow_per_area [Required]
A numerical value for the total volume flow rate of water per unit area of floor (L/h-m2).
schedule [Required]
A fractional schedule for the use of hot water over the course of the year. The fractional values will get multiplied by the _flow_per_area to yield a complete water usage profile.
target_temp
The target temperature of the water out of the tap in Celsius. This the temperature after the hot water has been mixed with cold water from the water mains. The default value assumes that the flow_per_area on this object is only for water straight out of the water heater. (Default: 60C).
sensible_fract
A number between 0 and 1 for the fraction of the total hot water load given off as sensible heat in the zone. (Default: 0.2).
latent_fract
A number between 0 and 1 for the fraction of the total hot water load that is latent (as opposed to sensible). (Default: 0.05).

Outputs

hot_water
A ServiceHotWater object that can be used to specify hot water usage in a ProgramType.

Setpoint

- [source code]

Create a Setpoint object that can be used to create a ProgramType or be assigned directly to a Room.

Inputs

name

Text to set the name for the Setpoint and to be incorporated into a unique Setpoint identifier. If None, a unique name will be generated.

heating_sch [Required]

A temperature schedule for the heating setpoint. The type limit of this schedule should be temperature and the values should be the temperature setpoint in degrees Celcius.

cooling_sch [Required]

A temperature schedule for the cooling setpoint. The type limit of this schedule should be temperature and the values should be the temperature setpoint in degrees Celcius.

humid_setpt

A numerical value between 0 and 100 for the relative humidity humidifying setpoint [%]. This value will be constant throughout the year. If None, no humidification will occur.

dehumid_setpt

A numerical value between 0 and 100 for the relative humidity dehumidifying setpoint [%]. This value will be constant throughout the year. If None, no dehumidification will occur beyond that which is needed to create air at the cooling supply temperature.

cutout_difference

Outputs

setpoint

A Setpoint object that can be used to create a ProgramType or be assigned directly to a Room.

Ventilation

- [source code]

Create a Ventilation object that can be used to create a ProgramType or be assigned directly to a Room.

Note the the 4 ventilation types (flow_per_person, flow_per_area, flow_per_zone, ach) are ultimately summed together to yeild the ventilation design flow rate used in the simulation.

Inputs

name
Text to set the name for the Ventilation and to be incorporated into a unique Ventilation identifier. If None, a unique name will be generated.
flow_per_person
A numerical value for the intensity of outdoor air ventilation in m3/s per person. This will be added to the flow_per_area, flow_per_zone and ach to produce the final minimum outdoor air specification. Note that setting this value here does not mean that ventilation is varied based on real-time occupancy but rather that the minimum level of ventilation is determined using this value and the People object of the Room. To vary ventilation on a timestep basis, a ventilation schedule should be used or the dcv_ option should be selected on the HVAC system if it is available. (Default: 0).
flow_per_area
A numerical value for the intensity of ventilation in m3/s per square meter of floor area. This will be added to the flow_per_person, flow_per_zone and ach to produce the final minimum outdoor air specification. (Default: 0).
flow_per_zone
A numerical value for the design level of ventilation in m3/s for the entire zone. This will be added to the flow_per_person, flow_per_area and ach to produce the final minimum outdoor air specification. (Default: 0).
ach
A numberical value for the design level of ventilation in air changes per hour (ACH) for the entire zone. This will be added to the flow_per_person, flow_per_area and flow_per_zone to produce the final minimum outdoor air specification. (Default: 0).
schedule
An optional fractional schedule for the ventilation over the course of the year. The fractional values will get multiplied by the total design flow rate (determined from the fields above and the calculation_method) to yield a complete ventilation profile. Setting this schedule to be the occupancy schedule of the zone will mimic demand controlled ventilation. If None, a constant design level of ventilation will be used throughout all timesteps of the simulation. (Default: None).

Outputs

vent
An Ventilation object that can be used to create a ProgramType or be assigned directly to a Room.

Airflow Newtwork

- [source code]

Set up a Honeybee Model to use the EnergyPlus Airflow Network (AFN) for all airflow in the energy simulation.

Compared to the default single-zone methods that Honeybee uses for infiltration and ventilation, the AFN represents air flow in a manner that is truer to the fluid dynamic behavior of real buildings. In particular, the AFN more accurately models the flow of air from one zone to another, accounting for the pressure changes induced by wind and air density differences. However, using the AFN means that the simulation will take considerably longer to run compared to the single zone option and the difference in simuation resuts is only likely to be significant when the Model contains operable windows or the building is extremely leaky.

Passing a Honeybee Model through this component before energy simulation will result in the following changes to the EnergyPlus IDF:

All ZoneInfiltration objects will be excluded and, instead, infitration will be modeled with AFN Crack objects assigned to each opaque Face.
For all AirBoundary Faces within the Model, ZoneMixing objects will be excluded and, instead, the air boundary will be modeled with AFN Crack objects that have very large pressure coefficients derived from the orifice equation and the area of the air wall.
For all operable Apertures, ZoneVentilation:WindandStackOpenArea objects will be excluded and, instead, these opearable apertures will be modeled with AFN SimpleOpening objects.
For each Room with a VentilationControl object to specify setpoints at which the windows open, an Energy Management System (EMS) program will be written to dictate when the operable Apertures of the Room open.

Inputs

model [Required]
A Honeybee Model for which the Airflow network will be set up. This Model should have everything assigned to it that is needed for simulation, including solved adjacencies and relevant window- opening properties.
leakage_template
Text identifying the leakiness of the Model, which is used to generate AFNCrack objects that represent infiltration for each of the Model's surfaces (Face, Aperture, and Door). Choose from the following.
- Excellent
- Medium
- VeryPoor These three text values correspond to DesignBuilder's Cracks Templates, which provide typical crack flow coefficients and exponents for different envelope tightness classifications. If None, the exterior airflow leakage parameters will be derived from the room infiltration rate specified in the room's energy properties, which are in units of m3/s per m2 of facade. This derivation from the Room's infiltration will compute air leakage parameters for exterior cracks that produce a total air flow rate equivalent to the room's infiltration rate at an envelope pressure difference of 4 Pa. This default derivation is not as complete of a representation of building ariflow dynamics as the DesignBuilder Crack Templates are. However, since the airflow leakae parameters are derived from values in m3/s-m2 of infiltration, they are easier to relate to the results of infiltration blower-door tests, which typically express infiltration rates in these units.
delta_pressure
The air pressure difference across the building envelope in Pascals, which is used to calculate infiltration crack flow coefficients when no leakage tempate is specified. The resulting average simulated air pressure difference will roughly equal this delta pressure times the nth root of the ratio between the simulated and target room infiltration rates. (Default: 4).
ref_pressure
The reference barometric pressure measurement in Pascals under which the surface crack data were obtained. (Default: 101325).
high_rise
Booling indicating whether the Model is LowRise or HighRise. This parameter is used to estimate building-wide wind pressure coefficients for the AFN by approximating the building geometry as an extruded rectangle. LowRise corresponds to a building where the height is less then three times the width AND length of the footprint. HighRise corresponds to a building where height is more than three times the width OR length of the footprint. If None, this property will be auto-calculated from Room geometry of the Model. This default assumption may not be appropriate if the Model represents only a portion of a larger Building.
long_axis
A number between 0 and 180 for the clockwise angle difference in degrees that the long axis of the building is from true North. This parameter is used to estimate building-wide wind pressure coefficients for the AFN by approximating the building geometry as an extruded rectangle. 0 indicates a North-South long axis while 90 indicates an East-West long axis. If None, this property will be auto-calculated from Room geometry of the Model (either 0 or 90). This default assumption may not be appropriate if the Model represents only a portion of a larger Building.
aspect_ratio
A number between 0 and 1 for the aspect ratio of the building's footprint, defined as the ratio of length of the short axis divided by the length of the long axis. This parameter is used to estimate building-wide wind pressure coefficients for the AFN by approximating the building geometry as an extruded rectangle If None, this property will be auto-calculated from Room geometry of the Model and the long_axis above. This default assumption may not be appropriate if the Model represents only a portion of a larger building.

Outputs

report
...
model
The input Honeybee Model for which the Airflow network has been set up.

Fan Ventilation

Add ventilation fans to Rooms.

This fan is not connected to any heating or cooling system and is meant to represent the intentional circulation of unconditioned outdoor air for the purposes of keeping a space cooler, drier or free of indoor pollutants (as in the case of kitchen or bathroom exhaust fans).

Inputs

rooms [Required]

Honeybee Rooms to which ventilation fans should be assigned.

name

Text to set the name for the ventilation fan and to be incorporated into a unique ventilation fan identifier. If None, a unique name will be generated.

flow_rate [Required]

A positive number for the flow rate of the fan in m3/s.

vent_type

Text to indicate the type of type of ventilation. Choose from the options below. For either Exhaust or Intake, values for fan pressure and efficiency define the fan electric consumption. For Exhaust ventilation, the conditions of the air entering the space are assumed to be equivalent to outside air conditions. For Intake and Balanced ventilation, an appropriate amount of fan heat is added to the entering air stream. For Balanced ventilation, both an intake fan and an exhaust fan are assumed to co-exist, both having the same flow rate and power consumption (using the entered values for fan pressure rise and fan total efficiency). Thus, the fan electric consumption for Balanced ventilation is twice that for the Exhaust or Intake ventilation types which employ only a single fan. (Default: Balanced).

pressure_rise

A number for the the pressure rise across the fan in Pascals (N/m2). This is often a function of the fan speed and the conditions in which the fan is operating since having the fan blow air through filters or narrow ducts will increase the pressure rise that is needed to deliver the input flow rate. The pressure rise plays an important role in determining the amount of energy consumed by the fan. Smaller fans like a 0.05 m3/s desk fan tend to have lower pressure rises around 60 Pa. Larger fans, such as a 6 m3/s fan used for ventilating a large room tend to have higher pressure rises around 400 Pa. The highest pressure rises are typically for large fans blowing air through ducts and filters, which can have pressure rises as high as 1000 Pa. If this input is None, the pressure rise will be estimated from the flow_rate, with higher flow rates corresponding to larger pressure rises (up to 400 Pa). These estimated pressure rises are generally assumed to have minimal obstructions between the fan and the room and they should be increased if the fan is blowing air through ducts or filters.

efficiency

A number between 0 and 1 for the overall efficiency of the fan. Specifically, this is the ratio of the power delivered to the fluid to the electrical input power. It is the product of the fan motor efficiency and the fan impeller efficiency. Fans that have a higher blade diameter and operate at lower speeds with smaller pressure rises for their size tend to have higher efficiencies. Because motor efficiencies are typically between 0.8 and 0.9, the best overall fan efficiencies tend to be around 0.7 with most typical fan efficiencies between 0.5 and 0.7. The lowest efficiencies often happen for small fans in situations with high pressure rises for their size, which can result in efficiencies as low as 0.15. If None, this input will be estimated from the fan flow rate and pressure rise with large fans operating at low pressure rises for their size having up to 0.7 efficiency and small fans operating at high pressure rises for their size having as low as 0.15 efficiency.

vent_cntrl

A Ventilation Control object from the "HB Ventilation Control" component that dictates the conditions under which the fan is turned on. If None, the fan on all of the time.

Outputs

report

Reports, errors, warnings, etc.

rooms

The input Rooms with ventilation fans assigned to them.

Ventilation Control

- [source code]

Create a Ventilation Control object to dictate the temperature setpoints and schedule for ventilative cooling (eg. opening windows).

Note the all of the default setpoints of this object are set to always perform ventilative cooling such that one can individually decide which setpoints are relevant to a given ventilation strategy.

Inputs

min_in_temp
A number between -100 and 100 for the minimum indoor temperature at which to ventilate in Celsius. Typically, this variable is used to initiate ventilation with values around room temperature above which the windows will open (eg. 22 C). (Default: -100 C).
max_in_temp
A number between -100 and 100 for the maximum indoor temperature at which to ventilate in Celsius. This can be used to set a maximum temperature at which point ventilation is stopped and a cooling system is turned on. (Default: 100 C).
min_out_temp
A number between -100 and 100 for the minimum outdoor temperature at which to ventilate in Celsius. This can be used to ensure ventilative cooling doesn't happen during the winter even if the Room is above the min_in_temp. (Default: -100 C).
max_out_temp
A number between -100 and 100 for the maximum outdoor temperature at which to ventilate in Celsius. This can be used to set a limit for when it is considered too hot outside for ventilative cooling. (Default: 100).
delta_temp
A number between -100 and 100 for the temperature differential in Celsius between indoor and outdoor below which ventilation is shut off. This should usually be a positive number so that ventilation only occurs when the outdoors is cooler than the indoors. Negative numbers indicate how much hotter the outdoors can be than the indoors before ventilation is stopped. (Default: -100).
schedule
An optional schedule for the ventilation over the course of the year. This can also be the name of a schedule to be looked up in the standards library. Note that this is applied on top of any setpoints. The type of this schedule should be On/Off and values should be either 0 (no possibility of ventilation) or 1 (ventilation possible). (Default: "Always On")

Outputs

vent_cntrl
HBZones with their airflow modified.

Window Opening

Define the window opening properties for all operable apertures of a Room.

By default, the properties assigned by this component are translated into simple ZoneVentilation objects in the resulting IIDF, which can approximate airflow from both single-sided bouyancy-driven ventilation as well as wind-driven cross ventilation. Bouyancy-driven flow can happen for essentially all openings while wind-driven flow can only happen when there are pressure differences across windows on opposite sides of a Room.

Simple ZoneVentilation is computed using the following formulas:

VentilationWind = WindCoefficient OpeningArea Schedule WindSpeed VentilationStack = StackDischargeCoefficient OpeningArea ScheduleValue SQRT(2 GravityAccelration HeightNPL * (|(TempZone - TempOutdoors)| / TempZone)) TotalVentilation = SQRT((VentilationWind)^2 + (VentilationStack)^2)

Note that the (OpeningArea) term is derived from the fract_area_oper and the area of each aperture while the (HeightNPL) term is derived from the fract_height_oper and the height of each aperture. The "NPL" stands for "Neutral Plane" and the whole term represents the height from midpoint of lower opening to the neutral pressure level of the window (computed as 1/4 of the height of each Aperture in the translation from honeybee to IDF).

More complex airflow phenomena can be modeled by using this component in conjunction with with the Airflow Network (AFN) component. Note that the window opening properties assigned by this component are still relevant for such AFN simulations.

Inputs

rooms [Required]
Honeybee Room objects to which window ventilation opening properties will be assigned. Note that this component only assigns such properties to operable Apertures on the rooms. If the is_operable property of any of a room's apertures is not True, no opening properties will be assigned.
vent_cntrl [Required]
A Ventilation Control object from the "HB Ventilation Control" component, which dictates the opening behaviour of the Room's apertures.
fract_area_oper
A number between 0.0 and 1.0 for the fraction of the window area that is operable. (Default: 0.5, typical of sliding windows).
fract_height_oper
A number between 0.0 and 1.0 for the fraction of the distance from the bottom of the window to the top that is operable. (Default: 1.0, typical of windows that slide horizontally).
discharge_coeff
A number between 0.0 and 1.0 that will be multipled by the area of the window in the stack (buoyancy-driven) part of the equation to account for additional friction from window geometry, insect screens, etc. (Default: 0.45, for unobstructed windows with insect screens). This value should be lowered if windows are of an awning or casement type and not allowed to fully open. Some common values for this coefficient include the following.
0.0 - Completely discount stack ventilation from the calculation.
0.45 - For unobstructed windows with an insect screen.
0.65 - For unobstructed windows with NO insect screen.
- wind_cross_vent
  Boolean to indicate if there is an opening of roughly equal area on the opposite side of the Room such that wind-driven cross ventilation will be induced. If False, the assumption is that the operable area is primarily on one side of the Room and there is no wind-driven ventilation. If None, the normal vectors of the operable aperturs of the input _rooms will be analyzed. If window normals of a given room are found to have an angle difference greater than 90 degrees, cross ventilation will be set to True. Otherwise, it will be False.

Outputs

report
...
rooms
The input Honeybee Rooms with their window-opening properties edited.

Blower Pressure Converter

Convert infiltration flow per exterior area measured at a particular blower door pressure to flow per exterior area measured at a typical building pressure.

This is accomplished by computing a normalized-area air mass flow coefficient that is derived the power law relationship between pressure and air flow. Cqa = Qblow / dPblow^n And then using the coefficient to approximate air flow at typical building pressure. Qbldg = Cqa * dPbldg^n

where: Cqa: Air mass flow coefficient per unit meter at 1 Pa [kg/m2/s/P^n] Qblow: Blower-induced volumetric air flow rate per area [m3/s/m2] dPblow: Blower-induced change in pressure across building envelope orifice [Pa] Qbldg: Typical building volumetric air flow rate per area [m3/s/m2] dPbldg: Typical building change in pressure across building envelope orifice [Pa] d: Air density [1.2041 kg/m3] n: Air mass flow exponent [0.65]

Inputs

infilt_per_exterior [Required]
A numerical value for the intensity of air flow induced by blower pressure in m3/s per square meter of exterior surface area.
blower_pressure
A number representing the pressure differential in Pascals (Pa) between indoors/outdoors at which the specified _infilt_per_exterior occurs. Typical pressures induced by blower doors are 75 Pa and 50 Pa. (Default: 75).
bldg_pressure
The reference air pressure difference across building envelope under typical conditions in Pascals. (Default: 4).

Outputs

infilt
The intensity of infiltration in m3/s per square meter of exterior surface area at the input bldg_pressure.
C_qa
Air mass flow coefficient per square meter at 1 Pa [kg/m2/s/P^n].

Deconstruct Equipment

Deconstruct an Equipment object into its constituient properties.

Inputs

equip [Required]
An ElectricEquipment or a GasEquipment object to be deconstructed.

Outputs

name
An Equipment object that can be used to create a ProgramType or be assigned directly to a Room.
watts_per_area
A numerical value for the equipment power density in Watts per square meter of floor area.
schedule
A fractional for the use of equipment over the course of the year. The fractional values will get multiplied by the watts_per_area to yield a complete equipment profile.
radiant_fract
A number between 0 and 1 for the fraction of the total equipment load given off as long wave radiant heat.
latent_fract
A number between 0 and 1 for the fraction of the total equipment load that is latent (as opposed to sensible).
lost_fract
A number between 0 and 1 for the fraction of the total equipment load that is lost outside of the zone and the HVAC system. Typically, this is used to represent heat that is exhausted directly out of a zone (as you would for a stove).
is_gas
Will be True if the input Equipment object is for GasEquipment; False if it is for ElectricEquipment.

Deconstruct Hot Water

Deconstruct a ServiceHotWater object into its constituient properties.

Inputs

hot_water [Required]
A ServiceHotWater object to be deconstructed.

Outputs

name
An Equipment object that can be used to create a ProgramType or be assigned directly to a Room.
flow_per_area
A numerical value for the total volume flow rate of water per unit area of floor (L/h-m2).
schedule
A fractional schedule for the use of hot water over the course of the year. The fractional values will get multiplied by the _flow_per_area to yield a complete water usage profile.
target_temp
The target temperature of the water out of the tap in Celsius. This the temperature after the hot water has been mixed with cold water from the water mains.
sensible_fract
A number between 0 and 1 for the fraction of the total hot water load given off as sensible heat in the zone.
latent_fract
A number between 0 and 1 for the fraction of the total hot water load that is latent (as opposed to sensible).

Deconstruct Infiltration

Deconstruct an Infiltration object into its constituient properties.

Inputs

infil [Required]
An Infiltration object to be deconstructed.

Outputs

name
Text string for the infiltration display name.
flow_per_ext_area
A numerical value for the intensity of infiltration in m3/s per square meter of exterior surface area. Typical values for this property are as follows (note all values are at typical building pressures of ~4 Pa):
- 0.0001 (m3/s per m2 facade) - Tight building
- 0.0003 (m3/s per m2 facade) - Average building
- 0.0006 (m3/s per m2 facade) - Leaky building
schedule
A fractional schedule for the infiltration over the course of the year. The fractional values will get multiplied by the flow_per_exterior_area to yield a complete infiltration profile.

Deconstruct Lighting

Deconstruct a Lighting object into its constituient properties.

Inputs

lighting [Required]
A Lighting object to be deconstructed.

Outputs

name
Text string for the lighting display name.
watts_per_area
A numerical value for the lighting power density in Watts per square meter of floor area.
schedule
A fractional for the use of lights over the course of the year. The fractional values will get multiplied by the watts_per_area to yield a complete lighting profile.
radiant_fract
A number between 0 and 1 for the fraction of the total lighting load given off as long wave radiant heat.
visible_fract
A number between 0 and 1 for the fraction of the total lighting load given off as short wave visible light.
return_fract
A number between 0 and 1 for the fraction of the total lighting load that goes into the zone return air.
baseline
The baseline lighting power density in W/m2 of floor area. This baseline is useful to track how much better the installed lights are in comparison to a standard like ASHRAE 90.1.

Deconstruct People

- [source code]

Deconstruct a People object into its constituient properties.

Inputs

people [Required]
A People object to deconstruct.

Outputs

name
Text string for the people object display name.
ppl_per_area
A numerical value for the number of people per square meter of floor area.
occupancy_sch
A fractional schedule for the occupancy over the course of the year. The fractional values in this schedule get multiplied by the _people_per_area to yield a complete occupancy profile.
activity_sch
A schedule for the activity of the occupants over the course of the year. The type limt of this schedule are "Power" and the values of the schedule equal to the number of Watts given off by an individual person in the room.

Deconstruct Setpoint

- [source code]

Deconstruct a Setpoint object into its constituient properties.

Inputs

setpoint [Required]
A Setpoint object to be deconstructed.

Outputs

name
Text string for the setpoint display name.
heating_sch
A temperature schedule for the heating setpoint. The type limit of this schedule should be temperature and the values should be the temperature setpoint in degrees Celcius.
cooling_sch
A temperature schedule for the cooling setpoint. The type limit of this schedule should be temperature and the values should be the temperature setpoint in degrees Celcius.
humid_setpt
A numerical value between 0 and 100 for the relative humidity humidifying setpoint [%]. This value will be constant throughout the year. If None, no humidification will occur.
dehumid_setpt
A numerical value between 0 and 100 for the relative humidity dehumidifying setpoint [%]. This value will be constant throughout the year. If None, no dehumidification will occur beyond that which is needed to create air at the cooling supply temperature.

Deconstruct Ventilation

- [source code]

Deconstruct a Ventilation object into its constituient properties.

Note the the 4 ventilation types (flow_per_person, flow_per_area, flow_per_zone, ach) are ultimately summed together to yeild the ventilation design flow rate used in the simulation.

Inputs

vent [Required]
An Ventilation object to be deconstructed.

Outputs

name
Text string for the ventilation display name.
flow_per_person
A numerical value for the intensity of ventilation in m3/s per person. Note that setting this value here does not mean that ventilation is varied based on real-time occupancy but rather that the design level of ventilation is determined using this value and the People object of the zone. To vary ventilation in real time, the ventilation schedule should be used. Most ventilation standards support that a value of 0.01 m3/s (10 L/s or ~20 cfm) per person is sufficient to remove odors.
flow_per_area
A numerical value for the intensity of ventilation in m3/s per square meter of floor area.
flow_per_zone
A numerical value for the design level of ventilation in m3/s for the entire zone.
ach
A numberical value for the design level of ventilation in air changes per hour (ACH) for the entire zone. This is particularly helpful for hospitals, where ventilation standards are often given in ACH.
schedule
An optional fractional schedule for the ventilation over the course of the year. The fractional values will get multiplied by the total design flow rate (determined from the fields above and the calculation_method) to yield a complete ventilation profile. If None, the design level of ventilation is used throughout all timesteps of the simulation.

4 :: HVAC

IdealAir

Apply a customized IdealAirSystem to Honeybee Rooms.

Inputs

rooms [Required]

Honeybee Rooms to which the input ideal air properties will be assigned. This can also be a Honeybee Model for which all conditioned Rooms will be assigned the ideal air system.

economizer

Text to indicate the type of air-side economizer used on the ideal air system. Economizers will mix in a greater amount of outdoor air to cool the zone (rather than running the cooling system) when the zone needs cooling and the outdoor air is cooler than the zone. Choose from the options below. (Default: DifferentialDryBulb).

dcv

Boolean to note whether demand controlled ventilation should be used on the system, which will vary the amount of ventilation air according to the occupancy schedule of the zone. (Default: False).

sensible_hr

A number between 0 and 1 for the effectiveness of sensible heat recovery within the system. (Default: 0).

latent_hr

A number between 0 and 1 for the effectiveness of latent heat recovery within the system. (Default: 0).

heat_temp

A number for the maximum heating supply air temperature [C]. (Default: 50; suitable for most air-based HVAC systems).

cool_temp

A number for the minimum cooling supply air temperature [C]. (Default: 13; sutiable for most air-based HVAC systems).

heat_limit

A number for the maximum heating capacity in Watts. This can also be the text 'autosize' to indicate that the capacity should be determined during the EnergyPlus sizing calculation. This can also be the text 'NoLimit' to indicate no upper limit to the heating capacity. (Default: 'autosize').

cool_limit

A number for the maximum cooling capacity in Watts. This can also be the text 'autosize' to indicate that the capacity should be determined during the EnergyPlus sizing calculation. This can also be the text 'NoLimit' to indicate no upper limit to the cooling capacity. (Default: 'autosize').

heat_avail

An optional on/off schedule to set the availability of heating over the course of the simulation. This can also be the identifier of an on/off schedule to be looked up in the schedule library (Default: None).

cool_avail

An optional on/off schedule to set the availability of cooling over the course of the simulation. This can also be the identifier of an on/off schedule to be looked up in the schedule library (Default: None).

Outputs

report

The execution information, as output and error streams

rooms

The input Rooms with their Ideal Air Systems edited.

Set Conditioned

- [source code]

Set Honeybee Rooms to be conditioned or unconditioned with a heating/cooling system.

If _conditioned is True and the connected rooms are not currently conditioned, an Ideal Air System will be assigned to them. Otherwise, if they are already conditioned, the existing HVAC system will be left as it is.

Inputs

rooms [Required]

Honeybee Rooms to have their conditioned property set.

conditioned [Required]

Boolean to indicate whether the rooms are conditioned with a heating/cooling system.

Outputs

rooms

Rooms that have had their interinal loads removed to reflect a plenum space.

All-Air HVAC

- [source code]

Apply an All-Air template HVAC to a list of Honeybee Rooms.

All-air systems provide both ventilation and satisfaction of heating + cooling demand with the same stream of warm/cool air. As such, they often grant tight control over zone humidity. However, because such systems often involve the cooling of air only to reheat it again, they are often more energy intensive than systems that separate ventilation from the meeting of thermal loads.

Inputs

rooms [Required]

Honeybee Rooms to which the input template HVAC will be assigned. This can also be a Honeybee Model for which all conditioned Rooms will be assigned the HVAC system.

system_type [Required]

Text for the specific type of all-air system and equipment. The "HB All-Air HVAC Templates" component has a full list of the supported all-air system templates.

vintage

Text for the vintage of the template system. This will be used to set efficiencies for various pieces of equipment within the system. The "HB Building Vintages" component has a full list of supported HVAC vintages. (Default: ASHRAE_2019).

name

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

economizer

Text to indicate the type of air-side economizer used on the HVAC system. Economizers will mix in a greater amount of outdoor air to cool the zone (rather than running the cooling system) when the zone needs cooling and the outdoor air is cooler than the zone. Choose from the options below. (Default: NoEconomizer).

* NoEconomizer

* DifferentialDryBulb

* DifferentialEnthalpy

* DifferentialDryBulbAndEnthalpy

* FixedDryBulb

* FixedEnthalpy

* ElectronicEnthalpy

sensible_hr

A number between 0 and 1 for the effectiveness of sensible heat recovery within the system. Typical values range from 0.5 for simple glycol loops to 0.81 for enthalpy wheels (the latter tends to be fiarly expensive for air-based systems). (Default: 0).

latent_hr

A number between 0 and 1 for the effectiveness of latent heat recovery within the system. Typical values are 0 for all types of heat recovery except enthalpy wheels, which can have values as high as 0.76. (Default: 0).

dcv

Boolean to note whether demand controlled ventilation should be used on the system, which will vary the amount of ventilation air according to the occupancy schedule of the zone. (Default: False).

Outputs

report

Reports, errors, warnings, etc.

rooms

The input Rooms with an all-air HVAC system applied.

All-Air HVAC Templates

- [source code]

Provides a list of available All-Air HVAC templates.

DOAS HVAC Templates

- [source code]

Provides a list of available Dedicated Outdoor Air System (DOAS) HVAC templates.

HeatCool HVAC

- [source code]

Apply a template system that only supplies heating and/or cooling (no ventilation) to Honeybee Rooms.

These systems are only designed to satisfy heating + cooling demand and they cannot meet any minimum ventilation requirements.

As such, these systems tend to be used in residential or storage settings where meeting minimum ventilation requirements may not be required or the density of occupancy is so low that infiltration is enough to meet fresh air demand.

Inputs

rooms [Required]

Honeybee Rooms to which the input template system will be assigned. This can also be a Honeybee Model for which all conditioned Rooms will be assigned the HVAC system.

system_type [Required]

Text for the specific type of heating/cooling system and equipment. The "HB HeatCool HVAC Templates" component has a full list of the supported Heating/Cooling system templates.

vintage

name

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

Outputs

report

Reports, errors, warnings, etc.

rooms

The input Rooms with a heating/cooling system applied.

HeatCool HVAC Templates

- [source code]

Provides a list of available template systems providing heating + cooling (without ventilation).

Weekly Schedule

- [source code]

Create a schedule from lists of daily values for each day of the week.

Inputs

sun [Required]

A list of 24 values that represent the schedule values at each hour of Sunday. This can also be a single constant value for the whole day.

mon [Required]

A list of 24 values that represent the schedule values at each hour of Monday. This can also be a single constant value for the whole day.

tue [Required]

A list of 24 values that represent the schedule values at each hour of Tuesday. This can also be a single constant value for the whole day.

wed [Required]

A list of 24 values that represent the schedule values at each hour of Wednesday. This can also be a single constant value for the whole day.

thu [Required]

A list of 24 values that represent the schedule values at each hour of Thursday. This can also be a single constant value for the whole day.

fri [Required]

A list of 24 values that represent the schedule values at each hour of Friday. This can also be a single constant value for the whole day.

sat [Required]

A list of 24 values that represent the schedule values at each hour of Saturday. This can also be a single constant value for the whole day.

holiday

An optional list of 24 values that represent the schedule values at each hour of holidays. This can also be a single constant value for the whole day. If no values are input here, the schedule for Sunday will be used for all holidays.

summer_des

An optional list of 24 values that represent the schedule values at each hour of the summer design day. This can also be a single constant value for the whole day. If None, the daily schedule with the highest average value will be used unless the type_limit is Temperature, in which case it will be the daily schedule with the lowest average value.

winter_des

An optional list of 24 values that represent the schedule values at each hour of the summer design day. This can also be a single constant value for the whole day. If None, the daily schedule with the lowest average value will be used unless the type_limit is Temperature, in which case it will be the daily schedule with the highest average value.

name

Text to set the name for the Schedule and to be incorporated into a unique Schedule identifier.

type_limit

A text string from the identifier of the ScheduleTypeLimit to be looked up in the schedule type limit library. This can also be a custom ScheduleTypeLimit object from the "HB Type Limit" component. The input here will be used to validate schedule values against upper/lower limits and assign units to the schedule values. Default: "Fractional" for values that range continuously between 0 and 1. Choose from the following built-in options:

* Fractional

* On-Off

* Temperature

* Activity Level

* Power

* Humidity

* Angle

* Delta Temperature

* Control Level

Outputs

report

Reports, errors, warnings, etc.

schedule

A ScheduleRuleset object that can be assigned to a Room, a Load object, or a ProgramType object.

idf_year

idf_week

idf_days

DOAS HVAC

- [source code]

Apply a Dedicated Outdoor Air System (DOAS) template HVAC to Honeybee Rooms.

DOAS systems separate minimum ventilation supply from the satisfaction of heating + cooling demand. Ventilation air tends to be supplied at neutral temperatures (close to room air temperature) and heating / cooling loads are met with additional pieces of zone equipment (eg. Fan Coil Units (FCUs)).

Because DOAS systems only have to cool down and re-heat the minimum ventilation air, they tend to use less energy than all-air systems. They also tend to use less energy to distribute heating + cooling by puping around hot/cold water or refrigerant instead of blowing hot/cold air. However, they do not provide as good of control over humidity and so they may not be appropriate for rooms with high latent loads like auditoriums, kitchens, laundromats, etc.

Inputs

rooms [Required]

Honeybee Rooms to which the input template HVAC will be assigned. This can also be a Honeybee Model for which all conditioned Rooms will be assigned the HVAC system.

system_type [Required]

Text for the specific type of DOAS system and equipment. The "HB DOAS HVAC Templates" component has a full list of the supported DOAS system templates.

vintage

name

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

sensible_hr

A number between 0 and 1 for the effectiveness of sensible heat recovery within the system. Typical values range from 0.5 for simple glycol loops to 0.81 for enthalpy wheels (the latter of which is a fairly common ECM for DOAS systems). (Default: 0).

latent_hr

dcv

Boolean to note whether demand controlled ventilation should be used on the system, which will vary the amount of ventilation air according to the occupancy schedule of the zone. (Default: False).

doas_avail_sch

An optional On/Off discrete schedule to set when the dedicated outdoor air system (DOAS) shuts off. This will not only prevent any outdoor air from flowing thorough the system but will also shut off the fans, which can result in more energy savings when spaces served by the DOAS are completely unoccupied. If None, the DOAS will be always on. (Default: None).