Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Provides a list of available climate zones in the library.
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.
See the Wiki of the lbt-grasshopper repository for the installation instructions for the entire Ladybug Tools Grasshopper plugin (including honeybee-grasshopper-energy).
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.
Provides a list of available building vintages in the library.
List of all energy attirbutes assigned to Honeybee Faces and Subfaces.
Create a ProgramType object by blending other ProgramTypes together using a weighted average based on program ratios.
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.
program
A ProgramType object that's a weighted average between the input _programs.
List of all energy attirbutes assigned to Honeybee Rooms.
Provides a list of available building programs in the ProgramType library.
Provides a list of available building construction types in the ConstructionSet library.
-
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.
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).
program
A ProgramType object that can be assigned to Honeybee Rooms in order to specify all default schedules and loads on the Room.
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.
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.
room_prog
A list of room program identifiers that meet the input criteria and can be applied to Honeybee Rooms.
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.
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.
constr_set
A ConstructionSet object that can be assigned to Honeybee Rooms in order to specify all default constructions on the Room.
Search for available ConstructionSets within the honeybee energy standards library.
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).
constr_sets
A list of ConstructionSet identifiers that can be applied to Honeybee Rooms.
-
Get a ConstructionSet from the standards library using a climate zone, building vintage and construction type.
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.
constr_set
A ConstructionSet identifier that can be applied to Honeybee Rooms.
Create a list of interior constructions that can be used to edit or create a ConstructionSet object.
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.
interior_set
A list of interior constructions that can be used to edit or create a ConstructionSet object.
Create a list of exterior constructions that can be used to edit or create a ConstructionSet object.
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).
exterior_set
A list of exterior constructions that can be used to edit or create a ConstructionSet object.
Make boundary conditions of Rooms or Faces adiabatic by face type.
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.
hb_objs
The input honeybee objects with their boundary conditions edited.
Create a list of ground constructions that can be used to edit or create a ConstructionSet object.
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).
ground_set
A list of ground constructions that can be used to edit or create a ConstructionSet object.
Create a list of exterior subface (apertures + doors) constructions that can be used to edit or create a ConstructionSet object.
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.
subface_set
A list of exterior subface constructions that can be used to edit or create a ConstructionSet object.
-
-
-
-
-
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.
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.
report
Reports, errors, warnings, etc.
rooms
The input Rooms with internal masses assigned.
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
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
rooms
Rooms that have had their properties altered to be representative of ground conditions.
Create a boundary condition representing a custom temperature and/or heat transfer coefficient on the other side of a face.
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).
bc
A BoundaryCondition object that can be assigned to any honeybee Face object (using the "HB Face" component or the "HB Properties by Guide Surface").
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.
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.
rooms
Rooms that have had their interinal loads removed to reflect a plenum space.
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.
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.
rooms
Rooms that have had their missing adjacencies patched.
Search for available Constructions within the honeybee energy standards library.
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.
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 for available Materials within the honeybee energy standards library.
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.
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 an opaque or window construction into its constituient materials.
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.
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 a construction set into its constituient exterior constructions.
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.
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.
-
Apply ConstructionSet to Honeybee Rooms or a Model.
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.
rooms
The input Rooms with their construction sets edited.
Deconstruct a material into its constituient attributes and values.
mat [Required]
A material to be deconstructed. This can also be text for a material to be looked up in the material library.
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 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.
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.
hb_objs
The input honeybee objects with their constructions edited.
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.
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.
constr
An opaque construction that can be assigned to Honeybee Faces or ConstructionSets.
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.
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.
hb_objs
The input honeybee objects with their constructions edited.
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.
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.
constr
A window construction that can be assigned to Honeybee Apertures or ConstructionSets.
Create an EnergyPlus shade construction. Note that Shade objects in EnergyPlus do not have layers and are only defined by their exterior reflectance.
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.
constr
A shade construction that can be assigned to Honeybee Shades or ConstructionSets.
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.
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.
constr
A shaded window construction that can be assigned to Honeybee Apertures or ConstructionSets.
Create an opaque material that has no mass, which can be plugged into the "HB Opaque Construction" component.
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.
mat
A no-mass opaque material that can be assigned to a Honeybee Opaque construction.
-
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.
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).
mat
A material for a shade layer in a window construction (like a roller shade) that can be assigned to a Honeybee Window construction.
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]
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).
mat
A custom gas gap material that describes a layer in a window construction and can be assigned to a Honeybee Window construction.
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.
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.
frame
A window frame material that can be assigned to a Honeybee Window construction.
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.
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).
mat
A window material that describes an entire glazing system, including glass, gaps, and frame and can be assigned to a Honeybee Window construction.
Create an EnergyPlus window construction with any number of dynamic states.
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.
constr
A dynamic window construction that can be assigned to Honeybee Apertures or ConstructionSets.
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.
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).
mat
A material for a blind layer in a window construction that can be assigned to a Honeybee Window construction.
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.
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).
mat
A vegetation material that can be assigned to a Honeybee Opaque construction.
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.
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.
mat
A window gas gap material that describes a layer in a window construction and can be assigned to a Honeybee Window construction.
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.
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".
report
Reports, errors, warnings, etc.
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".
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.
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.
Search for available Schedules within the honeybee energy standards library.
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.
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.
-
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.
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.
report
Reports, errors, warnings, etc.
mod_obj
The input Rooms or ProgramTypes with their schedules modified.
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.
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.
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 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.
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.
hb_objs
The input honeybee objects with their shade transmittance schedules edited.
Create a schedule from a single constant value or a list of 24 hourly values repeating continuously over every day of the year.
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
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.
Create a schedule defined by a list of values at a fixed interval or timestep running over the entirety of the simulation period.
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
report
Reports, errors, warnings, etc.
schedule
A ScheduleRuleset object that can be assigned to a Room, a Load object, or a ProgramType object.
Create a schedule using from other ScheduleRulesets and AnalysisPeriods over which each schedule should be applied.
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
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.
name
Text to set the name for the Schedule and to be incorporated into a unique Schedule identifier.
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.
-
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.
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
report
Reports, errors, warnings, etc.
type_limit
A ScheduleTypeLimit object that can be assigned to any schedule object.
Create a schedule from lists of daily values for each day of the week.
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:
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
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.
-
Apply ProgramType objects to Rooms or a Model.
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).
report
Reports, errors, warnings, etc.
rooms
The input Rooms with their loads edited.
-
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.
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).
report
Reports, errors, warnings, etc.
rooms
The input Rooms with their load values modified.
Deconstruct a ProgramType object into its component load objects.
program [Required]
A ProgramType object or text for the identifier of a ProgramType to be looked up in the program type library.
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 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.
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).
report
Reports, errors, warnings, etc.
rooms
The input Rooms with simple daylight controls assigned to them.
-
Apply values for setpoints to a Room or ProgramType.
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).
report
Reports, errors, warnings, etc.
mod_obj
The input Rooms or ProgramTypes with their setpoint values edited.
Create a Lighting object that can be used to create a ProgramType or be assigned directly to a Room.
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.
lighting
A Lighting object that can be used to create a ProgramType or be assigned directly to a Room.
Create an Infiltration object that can be used to create a ProgramType or be assigned directly to a Room.
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.
infil
An Infiltration object that can be used to create a ProgramType or be assigned directly to a Room.
-
Create an Equipment object that can be used to specify equipment usage in a ProgramType.
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).
equip
An Equipment object that can be used to specify equipment usage in a ProgramType.
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.
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.
report
Reports, errors, warnings, etc.
mod_obj
The input Rooms or ProgramTypes with their load values modified.
Create an ServiceHotWater object that can be used to specify hot water usage in a ProgramType.
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).
hot_water
A ServiceHotWater object that can be used to specify hot water usage in a ProgramType.
Create a Setpoint object that can be used to create a ProgramType or be assigned directly to a Room.
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
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).
setpoint
A Setpoint object that can be used to create a ProgramType or be assigned directly to a Room.
Create a People object that can be used to create a ProgramType or be assigned directly to a Room.
name
Text to set the name for the People and to be incorporated into a unique People identifier. If None, a unique name will be generated.
ppl_per_area [Required]
A numerical value for the number of people per square meter of floor area.
occupancy_sch [Required]
A fractional schedule for the occupancy over the course of the year. The fractional values in this schedule will 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 should be "Activity Level" 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.
latent_fraction
An optional number between 0 and 1 for the fraction of the heat given off by people that is latent (as opposed to sensible). when unspecified, this will be autocalculated based on the activity level and the conditions in the room at each timestep of the simulation. The autocalculation therefore accounts for the change in heat loss through respiration and sweating that occurs at warmer temperatures and higher activity levels, which is generally truer to physics compared to a fixed number.
people
A People object that can be used to create a ProgramType or be assigned directly to a Room.
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.
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).
vent
An Ventilation object that can be used to create a ProgramType or be assigned directly to a Room.
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.
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.
report
...
model
The input Honeybee Model for which the Airflow network has been set up.
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.
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.
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).
report
Reports, errors, warnings, etc.
rooms
The input Rooms with process loads assigned to them.
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).
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.
report
Reports, errors, warnings, etc.
rooms
The input Rooms with ventilation fans assigned to them.
-
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.
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")
vent_cntrl
HBZones with their airflow modified.
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.
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.
report
...
rooms
The input Honeybee Rooms with their window-opening properties edited.
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]
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).
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 a ServiceHotWater object into its constituient properties.
hot_water [Required]
A ServiceHotWater object to be deconstructed.
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 a People object into its constituient properties.
people [Required]
A People object to deconstruct.
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 an Equipment object into its constituient properties.
equip [Required]
An ElectricEquipment or a GasEquipment object to be deconstructed.
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 an Infiltration object into its constituient properties.
infil [Required]
An Infiltration object to be deconstructed.
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 a Lighting object into its constituient properties.
lighting [Required]
A Lighting object to be deconstructed.
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 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.
vent [Required]
An Ventilation object to be deconstructed.
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.
Deconstruct a Setpoint object into its constituient properties.
setpoint [Required]
A Setpoint object to be deconstructed.
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.
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.
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.
rooms
Rooms that have had their interinal loads removed to reflect a plenum space.
-
Apply a customized IdealAirSystem to Honeybee Rooms.
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).
report
The execution information, as output and error streams
rooms
The input Rooms with their Ideal Air Systems edited.
Provides a list of available All-Air HVAC templates.
Provides a list of available Dedicated Outdoor Air System (DOAS) HVAC templates.
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.
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).
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).
report
Reports, errors, warnings, etc.
rooms
The input Rooms with an all-air HVAC system applied.
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.
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
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.
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
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).
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).
report
Reports, errors, warnings, etc.
rooms
The input Rooms with a DOAS HVAC system applied.
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.
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
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 heating/cooling system and to be incorporated into unique system identifier. If the name is not provided, a random name will be assigned.
report
Reports, errors, warnings, etc.
rooms
The input Rooms with a heating/cooling system applied.
Apply a template Service Hot Water (SHW) system to Honeybee Rooms.
Note that the rooms must have hot water loads assigned to them in order for them to be connected to the system.
rooms [Required]
Honeybee Rooms to which the input template system will be assigned. This can also be a Honeybee Model for which all Rooms will be assigned the SHW system.
system_type [Required]
Text for the specific type of service hot water system and equipment. The "HB SHW Templates" component has a full list of the supported system templates.
name
Text to set the name for the Service Hot Water system and to be incorporated into unique system identifier. If the name is not provided, a random name will be assigned.
efficiency
A number for the efficiency of the heater within the system. For Gas systems, this is the efficiency of the burner. For HeatPump systems, this is the rated COP of the system. For electric systems, this should usually be set to 1. If unspecified this value will automatically be set based on the equipment_type. See below for the default value for each equipment type:
condition
A number for the ambient temperature in which the hot water tank is located [C]. This can also be a Room in which the tank is located. (Default: 22).
loss_coeff
A number for the loss of heat from the water heater tank to the surrounding ambient conditions [W/K]. (Default: 6 W/K).
report
Reports, errors, warnings, etc.
rooms
The input Rooms with a Service Hot Water system applied.
Provides a list of available Dedicated Outdoor Air System (DOAS) HVAC templates.
Provides a list of available template systems providing heating + cooling (without ventilation).
Set the properites of a Model's electric load center, which governs how on-site electricity generation is converted and distributed.
model [Required]
A Honeybee Model for which the electric load center properties will be set. This Model should include on-site power generation objects, like Shades with PV properties assigned, in order for the inputs here to have an effect on the simulation.
inverter_eff
A number between 0 and 1 for the load centers's inverter nominal rated DC-to-AC conversion efficiency. An inverter converts DC power, such as that output by photovoltaic panels, to AC power, such as that distributed by the electrical grid and is available from standard electrical outlets. Inverter efficiency is defined as the inverter's rated AC power output divided by its rated DC power output. (Default: 0.96).
dc_to_ac_size
A positive number (typically greater than 1) for the ratio of the inverter's DC rated size to its AC rated size. Typically, inverters are not sized to convert the full DC output under standard test conditions (STC) as such conditions rarely occur in reality and therefore unnecessarily add to the size/cost of the inverter. For a system with a high DC to AC size ratio, during times when the DC power output exceeds the inverter's rated DC input size, the inverter limits the array's power output by increasing the DC operating voltage, which moves the arrays operating point down its current-voltage (I-V) curve. The default value of 1.1 is reasonable for most systems. A typical range is 1.1 to 1.25, although some large-scale systems have ratios of as high as 1.5. The optimal value depends on the system's location, array orientation, and module cost. (Default: 1.1).
model
The input Honeybee Model with the electric load center properties set.
Adjust the properties of a Radiant HVAC that has been assigned to Honeybee Rooms.
Because Radiant HVAC systems interact with the conditioned rooms through the thermal mass of the constructions in which they are embedded, their design often requires
rooms [Required]
Honeybee Rooms that have a Radiant HVAC assigned to them, which are to have their radiant properties adjusted. This can also be a Honeybee Model for which all Rooms with a Radiant HVAC sill be adjusted.
radiant_type
Text to indicate which faces are thermally active by default. Note that systems are assumed to be embedded in concrete slabs with no insulation within the slab unless otherwise specified. Choose from the following. (Default: Floor).
min_op_time
A number for the minimum number of hours of operation for the radiant system before it shuts off. (Default: 1).
switch_time
A number for the minimum number of hours for when the system can switch between heating and cooling. (Default: 24).
report
The execution information, as output and error streams
rooms
The input Rooms with the radiant HVAC properties edited.
Apply a detailed Ironbug HVAC to Honeybee Rooms or a Honeybee Model.
hb_objs [Required]
Honeybee Rooms to which the input Ironbug HVAC will be assigned. This can also be a Honeybee Model for which the relevant Rooms referenced in the _hvac_system will be assigned the HVAC system.
hvac_system [Required]
A fully-detailed Irongbug HVAC system to be assigned to the input rooms (or model).
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.
report
Reports, errors, warnings, etc.
hb_objs
The input Rooms or Model with the detailed HVAC system applied.
Assign photovoltaic properties to a honeybee Shade such that it will generate electricity in energy simulations.
shades [Required]
Honeybee Shades to which photovoltaic properties will be assigned.
rated_efficiency
A number between 0 and 1 for the rated nameplate efficiency of the photovoltaic solar cells under standard test conditions (STC). Standard test conditions are 1,000 Watts per square meter solar irradiance, 25 degrees C cell temperature, and ASTM G173-03 standard spectrum. Nameplate efficiencies reported by manufacturers are typically under STC. Standard poly- or mono-crystalline silicon modules tend to have rated efficiencies in the range of 14-17%. Premium high efficiency mono-crystalline silicon modules with anti-reflective coatings can have efficiencies in the range of 18-20%. Thin film photovoltaic modules typically have efficiencies of 11% or less. (Default: 0.15 for standard silicon solar cells).
active_fraction
The fraction of the parent Shade geometry that is covered in active solar cells. This fraction includes the difference between the PV panel (aka. PV module) area and the active cells within the panel as well as any losses for how the (typically rectangular) panels can be arranged on the Shade geometry. When the parent Shade geometry represents just the solar panels, this fraction is typically around 0.9 given that the framing elements of the panel reduce the overall active area. (Default: 0.9).
module_type
Text or an integer to indicate the type of solar module. This is used to determine the temperature coefficients used in the simulation of the photovoltaic modules. Choose from the three options below. If unspecified, the module_type will be inferred from the rated_efficiency of these PVProperties using the rated efficiencies listed below.
mounting_type
Text or an integer to indicate the type of mounting and/or tracking used for the photovoltaic array. Note that the OneAxis options have an axis of rotation that is determined by the azimuth of the parent Shade geometry. Also note that, in the case of one or two axis tracking, shadows on the (static) parent Shade geometry still reduce the electrical output, enabling the simulation to account for large context geometry casting shadows on the array. However, the effects of smaller detailed shading may be improperly accounted for and self shading of the dynamic panel geometry is only accounted for via the tracking_gcr property. Choose from the following. (Default: FixedOpenRack).
loss_fraction
A number between 0 and 1 for the fraction of the electricity output lost due to factors other than EPW climate conditions, panel efficiency/type, active area, mounting, and inverter conversion from DC to AC. Factors that should be accounted for in this input include soiling, snow, wiring losses, electrical connection losses, manufacturer defects/tolerances/mismatch in cell characteristics, losses from power grid availability, and losses due to age or light-induced degradation. Losses from these factors tend to be between 10-20% but can vary widely depending on the installation, maintenance and the grid to which the panels are connected. The loss_fraction_from_components staticmethod on this class can be used to estimate this value from the various factors that it is intended to account for. (Default: 0.14).
tracking_gcr
A number between 0 and 1 that ONLY APPLIES TO ARRAYS WITH ONE AXIS mounting_type. The ground coverage ratio (GCR) is the ratio of module surface area to the area of the ground beneath the array, which is used to account for self shading of single-axis panels as they move to track the sun. A GCR of 0.5 means that, when the modules are horizontal, half of the surface below the array is occupied by the array. An array with wider spacing between rows of modules has a lower GCR than one with narrower spacing. A GCR of 1 would be for an array with no space between modules, and a GCR of 0 for infinite spacing between rows. Typical values range from 0.3 to 0.6. (Default: 0.4).
name
An optional text name for the photovoltaic properties. This can be useful for keeping track of different photovoltaics when using several of these components. If unspecified, a unique one will be generated.
report
Reports, errors, warnings, etc.
shades
The input Shades with photovoltaic properties assigned.
Write a honeybee Model to an OSM file (OpenStudio Model), which can then be translated to an IDF file and then run through EnergyPlus.
model [Required]
A honeybee model object possessing all geometry and corresponding energy simulation properties.
epw_file [Required]
Path to an .epw file on this computer as a text string.
sim_par
A honeybee Energy SimulationParameter object that describes all of the setting for the simulation. If None, some default simulation parameters will automatically be used.
measures
An optional list of measures to apply to the OpenStudio model upon export. Use the "HB Load Measure" component to load a measure into Grasshopper and assign input arguments. Measures can be downloaded from the NREL Building Components Library (BCL) at
add_str
THIS OPTION IS JUST FOR ADVANCED USERS OF ENERGYPLUS. You can input additional text strings here that you would like written into the IDF. The input here should be complete EnergyPlus objects as a single string following the IDF format. This input can be used to write objects into the IDF that are not currently supported by Honeybee.
folder
An optional folder on this computer, into which the IDF and result files will be written.
write [Required]
Set to "True" to write out the honeybee jsons (containing the Honeybee Model and Simulation Parameters) and write the OpenStudio Workflow (.osw) file with instructions for executing the simulation.
run
Set to "True" to translate the Honeybee jsons to an OpenStudio Model (.osm) and EnergyPlus Input Data File (.idf) and then simulate the .idf in EnergyPlus. This will ensure that all result files appear in their respective outputs from this component. This input can also be the integer "2", which will only translate the honeybee jsons to an osm and idf format without running the model through EnergyPlus. It can also be the integer "3", which will run the whole translation and simulation silently (without any batch windows).
report
Check here to see a report of the EnergyPlus run.
jsons
The file paths to the honeybee JSON files that describe the Model and SimulationParameter. These will be translated to an OpenStudio model.
osw
File path to the OpenStudio Workflow JSON on this machine. This workflow is executed using the OpenStudio command line interface (CLI) and it includes measures to translate the Honeybee model JSON as well as any other connected measures_.
osm
The file path to the OpenStudio Model (OSM) that has been generated on this computer.
idf
The file path of the EnergyPlus Input Data File (IDF) that has been generated on this computer.
sql
The file path of the SQL result file that has been generated on this computer. This will be None unless run_ is set to True.
zsz
Path to a .csv file containing detailed zone load information recorded over the course of the design days. This will be None unless run_ is set to True.
rdd
The file path of the Result Data Dictionary (.rdd) file that is generated after running the file through EnergyPlus. This file contains all possible outputs that can be requested from the EnergyPlus model. Use the "HB Read Result Dictionary" component to see what outputs can be requested.
html
The HTML file path containing all requested Summary Reports.
Run Honeybee objects capable of generating electricity (such as Shades with PV properties) through a quick energy simulation to obtain an estimate of electricity production.
Note that this component only evaluates electricity production and not energy consumption. Any number of Honeybee Rooms or other objects can be connected but they will only be simulated as context shade that casts shadows on the generator objects.
hb_objs [Required]
An array of honeybee Rooms, Faces, Apertures, Doors or Shades to be included in the simulation of electricity production. This can also be an entire Model to be simulated. Any number of Honeybee Rooms or non-generating objects can be connected but they will only be simulated as context shade that casts shadows on the generator objects.
epw_file [Required]
Path to an .epw file on your system as a text string.
north
A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).
inverter_eff
A number between 0 and 1 for the load centers's inverter nominal rated DC-to-AC conversion efficiency. An inverter converts DC power, such as that output by photovoltaic panels, to AC power, such as that distributed by the electrical grid and is available from standard electrical outlets. Inverter efficiency is defined as the inverter's rated AC power output divided by its rated DC power output. (Default: 0.96).
dc_to_ac_size
A positive number (typically greater than 1) for the ratio of the inverter's DC rated size to its AC rated size. Typically, inverters are not sized to convert the full DC output under standard test conditions (STC) as such conditions rarely occur in reality and therefore unnecessarily add to the size/cost of the inverter. For a system with a high DC to AC size ratio, during times when the DC power output exceeds the inverter's rated DC input size, the inverter limits the array's power output by increasing the DC operating voltage, which moves the arrays operating point down its current-voltage (I-V) curve. The default value of 1.1 is reasonable for most systems. A typical range is 1.1 to 1.25, although some large-scale systems have ratios of as high as 1.5. The optimal value depends on the system's location, array orientation, and module cost. (Default: 1.1).
run [Required]
Set to "True" to run the simulation to obtain annual loads. This can also be the integer 2 to run the simulation while being able to see the simulation process (with a batch window).
report
A report of the energy simulation run.
total_ac
A number for the total on-site produced alternating current (AC) electricity in kWh.
ac_power
A data collection of all on-site produced electricity (kWh). This represents the alternating current (AC) electricity coming out of the inverter that processes all on-site power production.
generators
A list of names for each of the electricity generation objects that were found among the connected _hb_objs. These names align with the tota_dc output below as well as the dc_power data collections.
total_dc
A list of numbers for the direct current (DC) electricity produced by each generator object in kWh.
dc_power
A list of data collections for the direct current (DC) electricity produced by each on-site electricity generator (kWh). Each photovoltaic object will have a separate data collection.
Run Honeybee Rooms through a quick energy simulation to obtain an estimate of annual heating, cooling, lighting, equipment, and service hot water loads.
Note that the default settings used by this component are only suitable for evaluating annual loads in the case where an error of up to 5% is acceptable. Also note that annual loads are not the same as annual energy use or utility costs and, while the "cop" inputs can be used to approximate some effects of real heating + cooling systems, any evaulation of actual energy use, utility costs, or GHG emissions should be done by modeling a detailed HVAC using the "HB Model to OSM" component.
rooms [Required]
A list of Honeybee Rooms for which annual loads will be computed.
shades
An optional list of Honeybee Shades that can block the sun to the input _rooms.
epw_file [Required]
Path to an .epw file on your system as a text string.
north
A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).
timestep
An integer for the number of timesteps per hour at which the energy balance calculation will be run. This has a dramatic impact on the speed of the simulation and the accuracy of results. Higher timesteps lead to longer simulations and more accurate results. At the lowest aceptable timestep of 1, the results can have an error up to 5% but increasing the timestep to 4 should drop errors to below 1%. (Default: 1). The following values are acceptable: (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60)
cool_cop
An optional number which the cooling load will be divided by to account for the relative importance of cooling loads compared to heating loads (aka. the Coefficient of Performance or COP). For most cooling systems, this is value greater than 1, though how much greater varies widely between cooling systems and it is ultimately a function of how close the temperature of the cooling system's heat sink is to the room temperature setpoints. If set to 1, the output cooling will be the energy that must be removed from the _rooms to meet the setpoint (aka. the cooling demand). (Default: 1).
heat_cop
An optional number which the heating load will be divided by to account for the relative importance of heating loads compared to cooling loads (aka. the Coefficient of Performance or COP). For fuel-based systems like gas boilers, this value tends to be less than 1 in order to represent the efficiency of the boiler and account for losses of heat, such as that through flue gases. For certain electric systems like heat pumps, this can be a value greater than 1 as such pumps may be able to pump more heat energy into a room per unit of electricity consumed. If set to 1, the output will be the energy that must be added to the _rooms to meet the setpoint (aka. the heating demand). (Default: 1).
run_bal
Set to True to have the full load balance computed after the simulation is run. This ensures that data collections for various terms of the load balance are output from the "balance". This can help explain why the loads are what they are but can also increase the component run time. (Default: False).
run [Required]
Set to "True" to run the simulation to obtain annual loads. This can also be the integer 2 to run the simulation while being able to see the simulation process (with a batch window).
report
A report of the energy simulation run.
total_load
A list of numbers for the 4-5 output load terms normalized by the floor area of the input _rooms. Units are kWh/m2. They are ordered as follows.
cooling
A monthly Data Collection for the cooling load intensity in kWh/m2.
heating
A monthly Data Collection for the heating load intensity in kWh/m2.
lighting
A monthly Data Collection for the lighting load intensity in kWh/m2.
equip
A monthly Data Collection for the equipment load intensity in kWh/m2. Typically, this is only the load from electric equipment but, if the attached _rooms have gas equipment, this will be a list of two data collections for electric and gas equipment respectively.
process
A monthly Data Collection for the process load intensity in kWh/m2.
hot_water
A monthly Data Collection for the service hot water load intensity in kWh/m2.
balance
A list of monthly data collections for the various terms of the floor-normalized load balance in kWh/m2. Will be None unless run_bal_ is set to True.
Create a custom simulation output object by plugging in one or more names of EnergyPlus simulation ouputs. The resulting object can be used to request output variables from EnergyPlus.
base_sim_output
An optional simulation output object to serve as the starting point for the sim_output object returned by this component. All of the output names will simply be appended to this initial starting object.
output_names
A list of EnergyPlus output names as strings (eg. 'Surface Window System Solar Transmittance'. These outputs will be requested from the simulation.
report_frequency
Text for the frequency at which the outputs are reported. Default: 'Hourly'. Choose from the following:
summary_reports
An optional list of EnergyPlus summary report names as strings. If None, only the 'AllSummary' report will be requested from the simulation and will appear in the HTML report output by EnergyPlus. See the Input Output Reference SummaryReports section for a full list of all reports that can be requested. https://bigladdersoftware.com/ epx/docs/9-1/input-output-reference/output-table-summaryreports.html
unmet_setpt_tol
A number in degrees Celsius for the difference that the zone conditions must be from the thermostat setpoint in order for the setpoint to be considered unmet. This will affect how unmet hours are reported in the output. ASHRAE 90.1 uses a tolerance of 1.11C, which is equivalent to 1.8F. (Default: 1.11C).
report
Report!
sim_output
A SimulationOutput object that can be connected to the "HB Simulation Parameter" component in order to specify which types of outputs should be written from EnergyPlus.
Visualize the desirability of shade in terms of its impact on the annual heating and cooling loads of Honeybee Rooms.
The calculation runs by performing a simple fast energy simulation of the connected Honeybee Rooms without any shade other than context. The resulting heating/cooling loads are extracted at each timestep of the simulation along with the direct (beam) solar gain through each of the Room's windows. Solar vectors are generated for each step of the simulation and projected from the Room's Aperture geometries through the shades assigned to those Apertures.
Solar vectors for timesteps when the Room is cooling mode contribute positively to shade desirability (shade help) while solar vectors for hours when the Room is heating mode contribute negatively (shade harm). This contribution is weighted by how much cooling or heating energy the Room requires at the timestep along with the direct solar gain through each Aperture at the timestep.
The component outputs a colored mesh of the shades assigned to the Room Apertures illustrating the net effect of shading each part of the geometry. A higher saturation of blue indicates that shading the cell is desirable. A higher saturation of red indicates that shading the cell is harmful (blocking more sun when the Room is in heating mode than cooling mode). Desaturated cells indicate that shading the cell will have relatively little effect on the heating or cooling loads of the Room.
The units for shade desirability are kWh of Room cooling load avoided per unit area of shade if the test cell of the shade is helpful (blue). If the test cell is harmful (red), the units are kWh of Room heating load increased per unit area of shade. So, if a given square meter of input _shade_geo has a shad desirability of 10 kWh/m2, this means that a shade in this location provides roughly 10 kWh of avoided cooling load to the parent Room over the year.
The method used by this component is based off of the Shaderade method developed by Jon Sargent, Jeffrey Niemasz and Christoph Reinhart. More information can be found in the following publication document: Sargent, Jon; Niemasz, Jeffrey; Reinhart, Christoph. SHADERADE: Combining Rhinoceros and EnergyPlus for the Design of Static Exterior Shading Devices. Building Simulation, 2011, Sydney, Australia. http://www.ibpsa.org/proceedings/bs2011/p_1209.pdf
rooms [Required]
A list of Honeybee Rooms for which cooling/heating shade benefit/harm will be evaluated. At least some of these Rooms should have Apertures with Shades assigned to them in order for this component to produce meaningful results. Note that all Shades generated with the "HB Louver Shades" component or the "HB Extruded Border" component are automatically assigned to a parent Aperture. For more complex Shade geometries, the "HB Add Shade" component can be used to assign the Shade to a parent Aperture.
context
Honeybee Shades representing context geometry that can block sun to the _rooms, therefore discounting any benefit or harm that could come to the Room's Shades.
epw_file [Required]
Path to an .epw file on your system as a text string. This will be used in the energy simulation to determine heating/cooling loads and to generate solar vectors for the shade benefit calculation.
north
A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).
grid_size [Required]
A positive number in Rhino model units for the size of grid cells at which the Shade geometries of the input _rooms will be subdivided for shade benefit analysis. The smaller the grid size, the higher the resolution of the analysis and the longer the calculation will take. So it is recommended that one start with a large value here and decrease the value as needed. However, the grid size should usually be smaller than the dimensions of the smallest piece of Shade geometry in order to yield meaningful results.
timestep
An integer for the number of timesteps per hour at which the energy simulation will run and sun vectors will be generated for the analysis. Higher values will result in the generation of more vectors, which will make the resulting shade meshes smoother and produce a better representation of real benefit/harm. However, the calculation will take longer as there are more intersection operations to perform. The default is 1 timestep per hour, which is the coarsest resolution avalable and the fastest calculation.
legend_par
Optional legend parameters from the "LB Legend Parameters" that will be used to customize the display of the results.
lag_time
A number for the amount of time in hours between when solar gain eneters the room and the gain results in an increased cooling load. Typically, it takes an hour or so for solar gains falling on the room floors to heat up the floor surface and then convect to the room air where the gain can be absorbed by a cooling system. This means that the cooling value associated with each sun vector should be a step or two after the time of the sun vector. Lag time can be longer than an hour if the room has a particularly high thermal mass or it may be shorter if the room has less mass or uses a radiant cooling system integrated into the floor where the sun is absorbed. Note that the value input here can be a decimal value to indicate that the lag time is a fraction of an hour. (Default: 1.0 hour).
cpu_count
An integer to set the number of CPUs used in the execution of the intersection calculation. If unspecified, it will automatically default to one less than the number of CPUs currently available on the machine or 1 if only one processor is available.
run [Required]
Set to "True" to run the component and perform shade benefit analysis.
report
...
vectors
The sun vectors that were used to evaluate the shade (note that these will increase as the timestep increases).
points
Points across the room Aperture geometry from which sun vectors are projected. Note that only Apertures with assigned Shades are evaluated in order to avoid unnessarily increasing the calculation time by evaluating windows for which there is not shade.
mesh
A colored mesh of the Shades assigned to the room's apertures showing where shading is helpful (blue), harmful (red), or does not make much of a difference (white or desaturated colors). Note that the colors can change depending upon the input legend_par_.
legend
Legend showing the numeric values of kWh per unit shade area of decreased/increased cooling/heating load that correspond to the colors in the shade mesh.
title
A text object for the study title.
shade_help
The cumulative kWh of avoided cooling load per square area unit obtained by shading the given cell. If a given square meter of shade geometry has a helpfulness of 10 kWh/m2, this means that a shade in this location decreases the cooling load of the Room by roughly 10 kWh over the year.
shade_harm
The cumulative kWh of increased heating load per square area unit obtained by shading the given cell. If a given square meter of shade geometry has a harmfulness of -10 kWh/m2, this means that a shade in this location increases the heating load of the Room by roughly 10 kWh over the year.
shade_net
The sum of the helpfulness and harmfulness for each cell. This will be negative if shading the cell has a net harmful effect and positive if the shade has a net helpful effect.
-
-
Create settings for the EnergyPlus Shadow Calculation.
solar_dist
An integer or text desribing how EnergyPlus should treat beam solar radiation and reflectances from surfaces that strike the building surfaces. Default is "FullExteriorWithReflections". Choose from the following.
0 = "MinimalShadowing" - In this case, exterior shadowing is only computedfor windows and not for other opaque surfaces that might have their surface temperature affected by the sun. All beam solar radiation entering the room is assumed to fall on the floor. A simple window view factor calculation is used to distribute incoming diffuse solar energy between interior surfaces.
1 = "FullExterior" - The simulation will perform the solar calculationin a manner that only accounts for direct sun and whether it is blocked by surrounding context geometry. For the inside of the building, all beam solar radiation entering the room is assumed to fall on the floor. A simple window view factor calculation is used to distribute incoming diffuse solar energy between interior surfaces.
2 = "FullInteriorAndExterior" - The simulation will perform the solarcalculation in a manner that models the direct sun (and wheter it is blocked by outdoor context goemetry. It will also ray trace the direct sun on the interior of rooms to distribute it correctly between interior surfaces. Any indirect sun or sun bouncing off of objects will not be modled. Note that, if you use this method without setting the calc_method to PixelCounting, EnergyPlus will give Severe warnings if your rooms have concave geometry (aka. are "L"-shaped). So it is recommended that this solar distribution only be used with the PixelCounting.
3 = "FullExteriorWithReflections" - [DEFAULT] The simulation will perform thesolar calculation in a manner that accounts for both direct sun and the light bouncing off outdoor surrounding context. For the inside of the building, all beam solar radiation entering the room is assumed to fall on the floor. A simple window view factor calculation is used to distribute incoming diffuse solar energy between interior surfaces.
4 = "FullInteriorAndExteriorWithReflections" - The simulation will performthe solar calculation in a manner that accounts for light bounces that happen both outside and inside the rooms. This is the most accurate method but will take longer to run. Note that, if you use this method without setting the calc_method to PixelCounting, EnergyPlus will give Severe warnings if your rooms have concave geometry (aka. are "L"-shaped). So it is recommended that this solar distribution only be used with the PixelCounting.
calc_method
Text noting whether CPU-based polygon clipping method or GPU-based pixel counting method should be used. For low numbers of shading surfaces (less than ~200), PolygonClipping requires less runtime than PixelCounting. However, PixelCounting runtime scales significantly better at higher numbers of shading surfaces. PixelCounting also has no limitations related to room concavity when used with any “FullInterior” solar distribution options. (Default: PolygonClipping). Choose from the following:
PolygonClipping
PixelCounting
update_method
Text describing how often the solar and shading calculations are updated with respect to the flow of time in the simulation. (Default: Periodic) Choose from the following:
Periodic
Timestep
frequency
Integer for the number of days in each period in which a unique shadow calculation will be performed. This field is only used if the AverageOverDaysInFrequency method is used in the previous field. Default - 30.
max_figures
Integer for the number of figures used in shadow overlaps. Default - 15000.
shadow_calc
A ShadowCalculation object that can be connected to the "HB Simulation Parameter" component in order to specify settings for the EnergyPlus Shadow Calculation.
Run Honeybee Rooms through a quick energy simulation to obtain an estimate of room-level peak cooling and heating on summer and winter design days.
rooms [Required]
A list of Honeybee Rooms for which peak loads will be computed.
shades
An optional list of Honeybee Shades that can block the sun to the input _rooms.
ddy_file [Required]
Path to a .ddy file on your system as a text string, which contains design day conditions for the peak load analysis. This can also be the path to an .epw file, in which case design days will be determined by statitically analysing the annual data to approximate 0.4% and 99.6% design conditions. Note that custom .ddy files can be crafted from EPW or STAT data using the "LB EPW to DDY" component. They can also also be created from raw sets of outdoor conditions using the "DF Construct Design Day" and "DF Write DDY" components. When constructing custom DDY files, it is recommended that the .ddy file contain only one summer and one winter design day. Alternatively, if you wish to specify multiple cooling design day conditions for each month of the year (to evaluate solar load in each month), each of these cooling design days should contain "0.4%" in the design day name along with " DB=>MWB". This convention will automatically be followed when using the "monthly_cool_" option on the "LB EPW to DDY" component. In this situation of multiple monthly cooling design days, this component will report peak_cool zone sizes that correspond to the highest month for each zone and the output cooling data collection will be for the month with the highest coincident peak cooling.
north
A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).
timestep
An integer for the number of timesteps per hour at which the energy simulation will be run and results reported. It is recommended that this be at least 6 but it can be increased to better capture the minute in which peak cooling occurs. (Default: 6). The following values are acceptable: (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60)
run_bal
Set to True to have the load balance computed after the simulation is run. This ensures that data collections for various terms of the load balance are output from the "balance". This can help explain why the loads are what they are but can also increase the component run time. (Default: False).
run [Required]
Set to "True" to run the simulation to obtain annual loads. This can also be the integer 2 to run the simulation while being able to see the simulation process (with a batch window).
report
A report of the energy simulation run.
peak_cool
A list of numbers that align with the input _rooms and correspond to the peak cooling of each room on the summer design day in Watts. Note that, for multi-room simulations, the individual room peaks may not be coincident, meaning that summing these values together won't give a correct sense of the size of cetral cooling equipment serving multiple rooms. For such equipment, the max of the cooling data collection should be used.
peak_heat
A list of numbers that align with the input _rooms and correspond to the peak heating of each room on the winter design day in Watts. Note that, for multi-room simulations, the individual room peaks may not be coincident, meaning that summing these values together won't give a correct sense of the size of cetral heating equipment serving multiple rooms. For such equipment, the max of the heating data collection should be used.
cooling
A Data Collection indicating the combined cooling demand of the rooms at each simulation timestep of the summer design day. This can be plugged into the "LB Monthly Chart" component to visualize the demand or it can be deconstructed with the "LB Deconstruct Data" component for analysis.
heating
A Data Collection indicating the combined heating demand of the rooms at each simulation timestepof the winter design day. This can be plugged into the "LB Monthly Chart" component to visualize the demand or it can be deconstructed with the "LB Deconstruct Data" component for analysis.
cool_bal
A list of data collections for the various terms of the sensible load balance that contribute to peak cooling on the summer design day. These can be plugged into the "LB Monthly Chart" component (with stack_ set to True) to visualize the terms contributing to the peak. Will be None unless run_bal_ is set to True.
heat_bal
A list of data collections for the various terms of the sensible load balance that contribute to peak heating on the summer design day. These can be plugged into the "LB Monthly Chart" component (with stack_ set to True) to visualize the terms contributing to the peak. Will be None unless run_bal_ is set to True.
Create simulation controls with instructions for which types of EnergyPlus calculations to run.
do_zone_sizing
Boolean for whether the zone sizing calculation should be run. Default: True.
do_system_sizing
Boolean for whether the system sizing calculation should be run. Default: True.
do_plant_sizing
Boolean for whether the plant sizing calculation should be run. Default: True.
for_sizing_period
Boolean for whether the simulation should be run for the sizing periods. Default: False.
for_run_period
Boolean for whether the simulation should be run for the run periods. Default: True.
sim_control
A SimulationControl object that can be connected to the "HB Simulation Parameter" component in order to specify which types of EnergyPlus calculations to run.
-
Create a simulation parameter object that carries a complete set of EnergyPlus simulation settings and can be plugged into the "HB Model To OSM" component.
north
A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0)
output
A SimulationOutput that lists the desired outputs from the simulation and the format in which to report them. This can be created using the "HB Simulation Output" component. Default is to request zone energy use at an hourly timestep.
run_period
A ladybyg AnalysisPeriod object to describe the time period over which to run the simulation. the default is to run the simulation for the whole year.
daylight_saving
An optional ladybug AnalysisPeriod object to describe start and end of daylight savings time in the simulation. If None, no daylight savings time will be applied to the simulation.
holidays
A list of Ladybug Date objects for the holidays within the simulation. These should be in the format of 'DD Month' (eg. '1 Jan', '25 Dec'). If None, no holidays are applied. Default: None.
start_dow
Text for the day of the week on which the simulation starts. Default: 'Sunday'. Choose from the following:
timestep
An integer for the number of timesteps per hour at which the calculation will be run. Default: 6. The following values are acceptable: (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60)
terrain
Text for the terrain type in which the model sits, used to determine the wind profile. Default: 'City'. Choose from:
sim_control
A SimulationControl object that describes which types of calculations to run. This can be generated from the "HB Simulation Control" component. Default: perform a sizing calculation but only run the simulation for the RunPeriod.
shadow_calc
A ShadowCalculation object describing settings for the EnergyPlus Shadow Calculation. This can be generated from the "HB Shadow Calculation" component. Default: Average over 30 days with FullExteriorWithReflections.
sizing
A SizingParameter object with criteria for sizing the heating and cooling system. This can be generated from the "HB Sizing Parameter" component.
sim_par
A SimulationParameter object that can be connected to the "HB Model To IDF" component in order to specify EnergyPlus simulation settings
Translate a fully-simualte-able OpenStudio model (.osm) to an IDF and run the it through EnergyPlus.
osm [Required]
Path to an OpenStudio Model (OSM) file as a text string. This can also be a list of OSM files.
epw_file [Required]
Path to an .epw file as a text string.
add_str
THIS OPTION IS JUST FOR ADVANCED USERS OF ENERGYPLUS. You can input additional text strings here that you would like written into the IDF. The strings input here should be complete EnergyPlus objects that are correctly formatted. This input can be used to write objects into the IDF that are not currently supported by Honeybee.
cpu_count
An integer to set the number of CPUs used in the execution of each connected OSM file. If unspecified, it will automatically default to one less than the number of CPUs currently available on the machine (or 1 if only one processor is available).
translate [Required]
Set to "True" to translate the OSM files to IDFs using the OpenStudio command line interface (CLI).
run
Set to "True" to run the resulting IDF through EnergyPlus.
This input can also be the integer "2", which will run the whole translation and simulation silently (without any batch windows).
report
Check here to see a report of the EnergyPlus run.
idf
The file path of the IDF file that has been generated on this computer.
sql
The file path of the SQL result file that has been generated on your machine. This will be None unless run_ is set to True.
zsz
Path to a .csv file containing detailed zone load information recorded over the course of the design days. This will be None unless run_ is set to True.
rdd
The file path of the Result Data Dictionary (.rdd) file that is generated after running the file through EnergyPlus. This file contains all possible outputs that can be requested from the EnergyPlus model. Use the Read Result Dictionary component to see what outputs can be requested.
html
The HTML file path of the Summary Reports. Note that this will be None unless the input sim_par denotes that an HTML report is requested and run_ is set to True.
Create a simulation output object by selecting sets of commonly-requested output variables. The resulting object can be used to request output variables from EnergyPlus.
zone_energy_use
Set to True to add outputs for zone energy use when ideal air systems are assigned. This includes, ideal air heating + cooling, lighting, electric + gas equipment, and fan electric energy.
system_energy_use
Set to True to add outputs for HVAC energy use from detailed systems. This includes outputs for different pieces of HVAC equipment, which together catch all energy-consuming parts of a system. (eg. chillers, boilers, coils, humidifiers, fans, pumps). It also includes the energy use of components of Service Hot Water (SHW) systems as well as any electricity generated on site, such at that coming from photovoltaics.
gains_and_losses
Set to True to Add outputs for zone gains and losses. This includes such as people gains, solar gains, infiltration losses/gains, and ventilation losses/gains.
comfort_metrics
Set to True to add outputs for zone thermal comfort analysis. This includes air temperature, mean radiant temperature, relative humidity, and unmet setpoint time.
surface_temperature
Set to True to add outputs for indoor and outdoor surface temperature.
surface_energy_flow
Set to True to add outputs for energy flow across all surfaces.
load_type
An optional text value to set the type of load outputs requested. Default - 'All'. Choose from the following:
report_frequency
Text for the frequency at which the outputs are reported. Default: 'Hourly'. Choose from the following:
report
Report!
sim_output
A SimulationOutput object that can be connected to the "HB Simulation Parameter" component in order to specify which types of outputs should be written from EnergyPlus.
Execute an OpenStudio workflow (.osw) and run the resulting IDF file through EnergyPlus.
osw [Required]
Path to an OSW file as a text string. This can also be a list of OSW files.
epw_file [Required]
Path to an .epw file as a text string.
add_str
THIS OPTION IS JUST FOR ADVANCED USERS OF ENERGYPLUS. You can input additional text strings here that you would like written into the IDF. The strings input here should be complete EnergyPlus objects that are correctly formatted. This input can be used to write objects into the IDF that are not currently supported by Honeybee.
cpu_count
An integer to set the number of CPUs used in the execution of each connected OSW file. If unspecified, it will automatically default to one less than the number of CPUs currently available on the machine (or 1 if only one processor is available).
translate [Required]
Set to "True" to execute the input OSWs using the OpenStudio command line interface (CLI). This will translate any honeybee jsons referenced in the osw to an osm and idf file.
run
Set to "True" to run the resulting IDF through EnergyPlus.
This input can also be the integer "2", which will run the whole translation and simulation silently (without any batch windows).
report
Check here to see a report of the EnergyPlus run.
osm
The file path to the OpenStudio Model (OSM) that has been generated on this computer.
idf
The file path of the IDF file that has been generated on this computer.
sql
The file path of the SQL result file that has been generated on your machine. This will be None unless run_ is set to True.
zsz
Path to a .csv file containing detailed zone load information recorded over the course of the design days. This will be None unless run_ is set to True.
rdd
The file path of the Result Data Dictionary (.rdd) file that is generated after running the file through EnergyPlus. This file contains all possible outputs that can be requested from the EnergyPlus model. Use the Read Result Dictionary component to see what outputs can be requested.
html
The HTML file path of the Summary Reports. Note that this will be None unless the input sim_par denotes that an HTML report is requested and run_ is set to True.
Load OpenStudio measures into Grasshopper and assign the measure's input arguments. The resulting measure object can be plugged into the "measures_" input of the "HB Model To OSM" component in order to be included in the export to OpenStudio.
Read more about OpenStudio measures and creating your own here: http://nrel.github.io/OpenStudio-user-documentation/reference/measure_writing_guide/
You can also download several measures created by others from here: https://bcl.nrel.gov/nrel/types/measure
measure_path [Required]
Path to the folder in which the measure exists. This folder must contain a measure.rb and a measure.xml file. Note that connecting an input here will transform the component, essentially removing this input and changing all of the other component inputs to be input arguments for the measure.
report
The execution information, as output and error streams
measure
A measure measure object can be plugged into the "measures_" input of the "HB Model To OSM" component in order to be included in the export to OpenStudio.
Create parameters with criteria for sizing the heating and cooling system.
ddy_file
An optional path to a .ddy file on your system, which contains information about the design days used to size the hvac system. If None, honeybee will look for a .ddy file next to the .epw and extract all 99.6% and 0.4% design days.
filter_ddays
Boolean to note whether the design days in the ddy_file_ should be filtered to only include 99.6% and 0.4% design days. If None or False, all design days in the ddy_file_ will be incorporated into the sizing parameters. This can also be the integer 2 to filter for 99.0% and 1.0% design days.
heating_fac
A number that will get multiplied by the peak heating load for each zone in the model in order to size the heating system for the model. Must be greater than 0. (Default: 1.25).
cooling_fac
A number that will get multiplied by the peak cooling load for each zone in the model in order to size the cooling system for the model. Must be greater than 0. (Default: 1.15).
eff_standard
Text to specify the efficiency standard, which will automatically set the efficiencies of all HVAC equipment when provided. Note that providing a standard here will cause the OpenStudio translation process to perform an additional sizing calculation with EnergyPlus, which is needed since the default efficiencies of equipment vary dependingon their size. THIS WILL SIGNIFICANTLY INCREASE TRANSLATION TIME TO OPENSTUDIO. However, it is often worthwhile when the goal is to match the HVAC specification with a particular standard. The "HB Building Vintages" component has a full list of supported HVAC efficiency standards. You can also choose from the following.
climate_zone
Text indicating the ASHRAE climate zone to be used with the efficiency_standard. When unspecified, the climate zone will be inferred from the design days. This input can be a single integer (in which case it is interpreted as A) or it can include the A, B, or C qualifier (eg. 3C). Typically, the "LB Import STAT" component can yield the climate zone for a particular location.
bldg_type
Text for the building type to be used in the efficiency_standard. If the type is not recognized or is None, it will be assumed that the building is a generic NonResidential. The following have meaning for the standard.
sizing
Parameters with criteria for sizing the heating and cooling system. These can be connected to the "HB Simulation Parameter" component in order to specify settings for the EnergyPlus simulation.
Parse all of the common Room-level comfort-related results from an SQL result file that has been generated from an energy simulation.
sql [Required]
The file path of the SQL result file that has been generated from an energy simulation.
face_indoor_temp
DataCollections for the indoor surface temperature of each surface (C).
face_outdoor_temp
DataCollections for the outdoor surface temperature of each surface (C).
face_energy_flow
DataCollections for the heat loss (negative) or heat gain (positive) through each building surfaces (kWh).
Run an IDF file through EnergyPlus.
idf [Required]
Path to an IDF file as a text string. This can also be a list of IDF files.
epw_file [Required]
Path to an .epw file as a text string.
add_str
THIS OPTION IS JUST FOR ADVANCED USERS OF ENERGYPLUS. You can input additional text strings here that you would like written into the IDF. The strings input here should be complete EnergyPlus objects that are correctly formatted. This input can be used to write objects into the IDF that are not currently supported by Honeybee.
cpu_count
An integer to set the number of CPUs used in the execution of each connected IDF file. If unspecified, it will automatically default to one less than the number of CPUs currently available on the machine (or 1 if only one processor is available).
run [Required]
Set to "True" to run the IDF through EnergyPlus. This input can also be the integer "2", which will run the whole simulation silently (without any batch windows).
report
Check here to see a report of the EnergyPlus run.
sql
The file path of the SQL result file that has been generated on your machine.
zsz
Path to a .csv file containing detailed zone load information recorded over the course of the design days.
rdd
The file path of the Result Data Dictionary (.rdd) file that is generated after running the file through EnergyPlus. This file contains all possible outputs that can be requested from the EnergyPlus model. Use the Read Result Dictionary component to see what outputs can be requested.
html
The HTML file path of the Summary Reports. Note that this will be None unless the input sim_par denotes that an HTML report is requested and _run is set to True.
Run an OpenStudio Meausre that is intended to create an entire OSM file (OpenStudio Model). Examples of such measures include the "Create DOE Prototype Building" measure such as that wich can be downloaded here:
https://github.com/NREL/openstudio-model-articulation-gem/tree/develop/lib/ measures/create_DOE_prototype_building
measure [Required]
A Measure from the "HB Load Measure" component that is intended to generate an OSM from input arguments. Measures can be downloaded from the NREL Building Components Library (BCL) at (https://bcl.nrel.gov/).
add_str
Optional additional text strings here to be written into the IDF. The input here should be complete EnergyPlus objects as a single string following the IDF format. This can be used to add addition EnergyPlus outputs in the resulting IDF among other features.
folder
An optional folder on this computer, into which the IDF and OSM files will be written. If none, a sub-folder within the default simulation folder will be used.
run [Required]
Script variable Python
out
The execution information, as output and error streams
osw
File path to the OpenStudio Workflow JSON on this machine. This workflow is executed using the OpenStudio command line interface (CLI) and it includes measures to create the OSM from the measure
osm
The file path to the OpenStudio Model (OSM) that has been generated on this computer.
idf
The file path of the EnergyPlus Input Data File (IDF) that has been generated on this computer.
-
-
Get information about end use intensity from an EnergyPlus SQL file.
sql [Required]
The file path of the SQL result file that has been generated from an energy simulation. This can also be a list of EnergyPlus files in which case, EUI will be computed across all files.
ip
Boolean to note whether the EUI should be in SI (kWh/m2) or IP (kBtu/ft2) units. (Default: False).
eui
The total end use intensity result from the simulation. Specifically, this is the sum of all electricity, fuel, district heating/cooling, etc. divided by the gross floor area (including both conditioned and unconditioned spaces). The value will be in kWh/m2 if ip_ is False or None and kBtu/ft2 if True.
eui_end_use
The end use intensity result from the simulation, broken down by each end use. These values coorespond to the enduses output below. Values will be in kWh/m2 if ip is False or None and kBtu/ft2 if True.
end_uses
A list of text for each of the end uses in the simulation (Heating, Cooling, etc.). Thes outputs coorespond to the eui_end_use output above.
gross_floor
The total gross floor area of the energy model. This can be used to compute the total energy use from the intensity values above or it can be used to help with other result post-processing. The value will be in m2 if ip_ is False or None and ft2 if True.
Parse any time series data from an energy simulation SQL result file.
sql [Required]
The file path of the SQL result file that has been generated from an energy simulation.
output_names [Required]
A list of EnergyPlus output names as strings (eg. 'Surface Window System Solar Transmittance'. These data corresponding to these outputs will be returned from this component.
results
DataCollections for the output_names.
Parse the peak load and HVAC component sizes from an SQL result file that has been generated from an energy simulation.
sql [Required]
The file path of the SQL result file that has been generated from an energy simulation.
comp_type
An optional name of a HVAC component type, which will filter the HVAC components that appear in the output comp_props and comp_values. Connecting nothing here will mean that all HVAC component sizes are imported and a full list of possible components will appear in the comp_types output.
zone_names
A list of zone names (honeybee Room identifiers) that correspond to the zone_peak_load and zone_peak_heat below.
zone_peak_cool
A list of numbers for the peak cooling load of each zone on the summer design day. These correspond to the zone_names above. All values are in Watts.
zone_peak_heat
A list of numbers for the peak heating load of each zone on the winter design day. These correspond to the zone_names above. All values are in Watts.
comp_types
A list of HVAC component types that are available in the results. This will be equal to the input comp_type_ if a value is connected.
comp_properties
A list of text descriptions for HVAC component properties. These correspond to the comp_values below.
comp_values
Values denoting the size of various zone HVAC components (eg. zone terminal sizes, boiler/chiller sizes, lengths of chilled beams, etc.). These correspond to the comp_properties above. Values may be in different units (eg. W, m/s, etc.) depending on the property of the component being observed.
Parse all of the common Room-level comfort-related results from an SQL result file that has been generated from an energy simulation.
sql [Required]
The file path of the SQL result file that has been generated from an energy simulation.
oper_temp
DataCollections for the mean operative temperature of each room (C).
air_temp
DataCollections for the mean air temperature of each room (C).
rad_temp
DataCollections for the mean radiant temperature of each room (C).
rel_humidity
DataCollections for the relative humidity of each room (%).
unmet_heat
DataCollections for time that the heating setpoint is not met in each room (hours).
unmet_cool
DataCollections for time that the cooling setpoint is not met in each room (hours).
Parse all of the common Room-level energy-related results from an SQL result file that has been generated from an energy simulation.
sql [Required]
The file path of the SQL result file that has been generated from an energy simulation.
cooling
DataCollections for the cooling energy in kWh. For Ideal Air loads, this output is the sum of sensible and latent heat that must be removed from each room. For detailed HVAC systems, this output will be electric energy needed to power each chiller/cooling coil.
heating
DataCollections for the heating energy needed in kWh. For Ideal Air loads, this is the heat that must be added to each room. For detailed HVAC systems, this will be fuel energy or electric energy needed for each boiler/heating element.
lighting
DataCollections for the electric lighting energy used for each room in kWh.
electric_equip
DataCollections for the electric equipment energy used for each room in kWh.
gas_equip
DataCollections for the gas equipment energy used for each room in kWh.
process
DataCollections for the process load energy used for each room in kWh.
hot_water
DataCollections for the service hote water energy used for each room in kWh.
fan_electric
DataCollections for the fan electric energy in kWh for either a ventilation fan or a HVAC system fan.
pump_electric
DataCollections for the water pump electric energy in kWh for a heating/cooling system.
people_gain
DataCollections for the internal heat gains in each room resulting from people (kWh).
solar_gain
DataCollections for the total solar gain in each room (kWh).
infiltration_load
DataCollections for the heat loss (negative) or heat gain (positive) in each room resulting from infiltration (kWh).
mech_vent_load
DataCollections for the heat loss (negative) or heat gain (positive) in each room resulting from the outdoor air coming through the HVAC System (kWh).
nat_vent_load
DataCollections for the heat loss (negative) or heat gain (positive) in each room resulting from natural ventilation (kWh).
Visualize face and sub-face level energy simulation results as colored geometry.
data [Required]
A list of data collections of the same data type, which will be used to color Faces with simulation results. Data collections can be of any class (eg. MonthlyCollection, DailyCollection) but they should all have headers with metadata dictionaries with 'Surface' keys. These keys will be used to match the data in the collections to the input faces.
hb_objs [Required]
An array of honeybee Rooms, Faces, Apertures or Doors to be colored with simulation results in the Rhino scene. This can also be an entire Model to be colored.
normalize
Boolean to note whether results should be normalized by the face/sub-face area if the data type of the data_colections supports it. If False, values will be generated using sum total of the data collection values. Note that this input has no effect if the data type of the data_collections is not normalizable since data collection values will always be averaged for this case. (Default: True).
sim_step
An optional integer (greater than or equal to 0) to select a specific step of the data collections for which result values will be generated. If None, the geometry will be colored with the total of resutls in the data_collections if the data type is cumulative or with the average of results if the data type is not cumulative. (Default: None).
period
A Ladybug analysis period to be applied to all of the input _data.
legend_par
An optional LegendParameter object to change the display of the ColorRooms.
report
...
mesh
A colored mesh of the face/sub-face geometry colored using the input _data. Multiple meshes will be output for several data collections are input.
wire_frame
A list of polylines representing the outline of the faces.
legend
Geometry representing the legend for the colored favess.
title
A text object for the global title.
faces
A list of honeybee Face, Aperture and Door objects that have been matched to the input _data. This can be plugged into the "HB Visualize Quick" component to get face breps that are colored.
colors
A list of color objects that align with the output faces. These can be connected to a native Grasshopper "Custom Preview" component in order to color room volumes with results.
values
A list of numbers for each of the faces, which are used to generate the colors.
vis_set
An object containing VisualizationSet arguments for drawing a detailed version of the ColorRoom in the Rhino scene. This can be connected to the "LB Preview Visualization Set" component to display this version of the visualization in Rhino.
Get all the data within a table of a Summary Report using the table name.
All of the avaialable tables can be browsed by opening the .html output from the simulation in a web browser.
sql [Required]
The file path of the SQL result file that has been generated from an energy simulation.
table_name [Required]
Text string for the name of a table of a Summary Report. Examples include: General, Utility Use Per Conditioned Floor Area, and many more options that can be browsed in the .html file.
values
A data tree represening the table matrix, with each branch (sub-list) of the tree representing a row of the table and each index of each branch corresponding to a value in a column. The order of outputs should reflect how the table appears in the HTML output. Note that any energy values in MJ or GJ in the .html output will automatically be converted to kWh on import.
col_names
A list of text for the names of each of the columns in the table. These order of this list corresponds directly to the order of items each of the values sub-list
row_names
A list of text for the names of each of the rows of the table. Each name in this list corresponds to a branch in the output values data tree.
Calculate a building (or zone) balance temperature from a ideal air load simulation results. The balance point is the outdoor temperature at which a building switches between heating and cooling.
If the outdoor temperture drops below the balance temperature, the building will usually be in heating mode and, if the outdoor temperture is above the balance temperature, the building will usually be in cooling mode.
The balance temperture concept is useful for setting things such as automated blinds and airflow schedules since having these things directly controlled by hourly cooling or heating demand isn't always straightforward.
This component works by taking the average combined heating/cooling values for each day and the average outdoor air temperature for each day. The days with the smallest combined heating + cooling will have their daily mean outdoor air tempertures averaged to produce the output balance temperture.
cooling [Required]
Data collection for the annual hourly or daily ideal air cooling load output from the "HB Read Room Energy Result" component. This can be for a single room or the entire model.
heating [Required]
Data collection for the annual hourly or daily ideal air heating load output from the "HB Read Room Energy Result" component. This can be for a single room or the entire model.
temperature [Required]
Data collection for the annual hourly or daily outdoor temperature. Most of the time, this should be the dry bulb temperature from the "LB Import EPW" component. However other types of temperature like sky temperature may improve accuracy since they include the effects of solar gain. Note that, whatever type of temperature is plugged in here determines the type of balance temperature that is output.
day_count
An integer for the number of days with a low thermal energy load that will be averaged together to yield the balance point. The use of multiple days is done to help avoid anomalies introduced by things like variations between weekday and weekend shcedules. It is recommended that this be increased for models with particularly high variation in schedules. (Default: 10).
bal_day_load
The average thermal load on the balance day. This number should be close to 0 if the balance temperature is accurate and this output is meant to give a sense of the accuracy of the balance temperature value.
bal_temp
The outdoor balance temperature.
Separate data collections of energy simulation results by object and face type. Input data must be for Faces, Apertures, Doors, or any combination of these objects.
This component can also be used to normalize such data by area.
data [Required]
A list of data collections output from an energy simulation, which will be separated by object and face type. Data collections can be of any class (eg. MonthlyCollection, DailyCollection) but they should all have headers with metadata dictionaries with 'Surface' keys. These keys will be used to match the data in the collections to the input faces.
hb_objs [Required]
An array of honeybee Rooms, Faces, Apertures or Doors, which will be matched with the _data. This can also be an entire Model.
norm
Boolean to note whether results should be normalized by the face/sub-face area if the data type of the data_colections supports it. (Default: False)
walls
Data collections with results for Walls with an Outdoors or Ground boundary condition.
interior_walls
Data collections with results for Walls with a Surface or Adiabatic boundary condition.
roofs
Data collections with results for RoofCeilings with an Outdoors or Ground boundary condition.
ceilings
Data collections with results for RoofCeilings with a Surface or Adiabatic boundary condition.
exterior_floors
Data collections with results for Floors with an Outdoors or Ground boundary condition.
interior_floors
Data collections with results for Floors with a Surface or Adiabatic boundary condition.
apertures
Data collections with results for Apertures with an Outdoors boundary condition.
interior_apertures
Data collections with results for Apertures with a Surface boundary condition.
doors
Data collections with results for Doors with an Outdoors boundary condition.
interior_doors
Data collections with results for Doors with a Surface boundary condition.
Visualize Room-level energy simulation results as colored Room geometry.
data [Required]
A list of data collections of the same data type, which will be used to color Rooms. Data collections can be of any class (eg. MonthlyCollection, DailyCollection) but they should originate from an energy simulation sql (with header metadata that has 'Zone' or, in some cases, 'System' keys). These keys will be used to match the data in the collections to the input rooms.
rooms_model [Required]
An array of honeybee Rooms or honeybee Models, which will be matched to the data_collections. The length of these Rooms does not have to match the data_collections and this object will only create visualizations for rooms that are found to be matching.
norm_by_flr
Boolean to note whether results should be normalized by the floor area of the Room if the data type of the data_colections supports it. If False, values will be generated using sum total of the data collection values. Note that this input has no effect if the data type of the data_collections is not cumulative since data collection values will always be averaged for this case. Default: True.
sim_step
An optional integer (greater than or equal to 0) to select a specific step of the data collections for which result values will be generated. If None, the geometry will be colored with the total of resutls in the data_collections if the data type is cumulative or with the average of results if the data type is not cumulative. Default: None.
period
A Ladybug analysis period to be applied to all of the input _data.
legend_par
An optional LegendParameter object to change the display of the ColorRooms.
report
...
mesh
A colored mesh of the Room floor geometry colored using the input _data. Multiple meshes will be output for several data collections are input.
wire_frame
A list of polylines representing the outline of the room volumes.
legend
Geometry representing the legend for the colored rooms.
title
A text object for the global title.
rooms
A list of honeybee Room objects that have been successfully matched to the input _data. This can be plugged into the "HB Visualize Quick" component to get full room volumes that are colored.
colors
A list of color objects that align with the output rooms. These can be connected to a native Grasshopper "Custom Preview" component in order to color room volumes with results.
values
A list of numbers for each of the rooms, which are used to generate the colors.
vis_set
An object containing VisualizationSet arguments for drawing a detailed version of the ColorRoom in the Rhino scene. This can be connected to the "LB Preview Visualization Set" component to display this version of the visualization in Rhino.
Construct a complete thermal load balance from energy simulation results and honeybee Rooms or a Model.
rooms_model [Required]
An array of honeybee Rooms or a honeybee Model for which the thermal load balance will be computed. In most cases, these should be the Rooms or Model that are fed directly into the simulation. But this can also be a subset of such Rooms and the balance will only be computed for those Rooms.
cooling
Array of data collections for 'Zone Ideal Loads Supply Air Cooling Energy'.
heating
Array of data collections for 'Zone Ideal Loads Supply Air Heating Energy'.
lighting
Array of data collections for 'Zone Lights Heating Energy'.
electric_equip
Array of data collections for 'Zone Electric Equipment Heating Energy'.
gas_equip
Array of data collections for 'Zone Gas Equipment Heating Energy'.
process
Array of data collections for 'Zone Other Equipment Total Heating Energy'.
hot_water
Array of data collections for 'Water Use Equipment Zone Heat Gain Energy' that correspond to the input rooms.
people_gain
Array of data collections for 'Zone People Heating Energy'.
solar_gain
Array of data collections for 'Zone Windows Transmitted Solar Radiation Energy'.
infiltration_load
An array of data collections for the infiltration heat loss (negative) or heat gain (positive).
mech_vent_load
An array of data collections for the ventilation heat loss (negative) or heat gain (positive) as a result of meeting minimum outdoor air requirements with the mechanical system.
nat_vent_load
An array of data collections for the natural ventilation heat loss (negative) or heat gain (positive).
face_energy_flow
An array of data collections for the surface heat loss (negative) or heat gain (positive).
report
...
balance
A list of data collections where each collection represents a load balance term. This can then be plugged into the "LB Hourly Plot" or "LB Monthly Chart" to give a visualization of the load balance over all connected Rooms.
balance_stor
The balance output plus an additional term to represent the remainder of the load balance. This term is labeled "Storage" since it typically represents the energy being stored in the building's mass. If this term is particularly large, it can indicate that not all of the load balance terms have been plugged into this component.
norm_bal
A list of data collections where each collection represents a load balance term that has bee normalized by the Room floor area. This can then be plugged into the "LB Hourly Plot" or "LB Monthly Chart" to give a visualization of the load balance over all connected Rooms.
norm_bal_stor
The norm_bal output plus an additional term to represent the remainder of the load balance. This term is labeled "Storage" since it typically represents the energy being stored in the building's mass. If this term is particularly large, it can indicate that not all of the load balance terms have been plugged into this component.
Normalize Zone-level data collections from an energy simulation by the by the floor area of the corresponding honeybee Rooms.
data [Required]
A list of HourlyContinuousCollections of the same data type, which will be normalized by room floor area. Data collections can be of any class (eg. MonthlyCollection, DailyCollection) but they should originate from an energy simulation sql (with header metadata that has 'Zone' or 'System' keys). These keys will be used to match the data in the collections to the input rooms.
model [Required]
An array of honeybee Rooms or a honeybee Model, which will be matched to the data collections. The length of these Rooms does not have to match the data collections and this object will only output collections for rooms that are found to be matching.
total_data
The total results normalized by the floor area of all connected rooms. This accounts for the fact that some rooms have more floor area (or have a multiplier) and therefore get a greater weighting.
room_data
The results normalized by the floor area of each individual room.
Compute spatially-resolved Universal Thermal Climate Index (UTCI) and heat/cold stress conditions an EPW and Honeybee model.
This recipe uses EnergyPlus to obtain surface temperatures and indoor air temperatures + humidities. Outdoor air temperatures, relative humidities, and air speeds are taken directly from the EPW. The energy properties of the model geometry are what determine the outcome of the simulation, though the model's Radiance sensor grids are what determine where the comfort mapping occurs.
Longwave radiant temperatures are obtained by computing spherical view factors from each sensor to the Room surfaces of the model using Radiance. These view factors are then multiplied by the surface temperatures output by EnergyPlus to yield longwave MRT at each sensor. For outdoor sensors, each sensor's sky view is multiplied by the EPW sky temperature to account for longwave radiant exchange with the sky. All outdoor context shades and the ground are assumed to be at the EPW air temperature unless they have been modeled as Honeybee rooms.
A Radiance-based enhanced 2-phase method is used for all shortwave MRT calculations, which precisely represents direct sun by tracing a ray from each sensor to the solar position. To determine Thermal Comfort Percent (TCP), the occupancy schedules of the energy model are used for indoor sensors if no schedule_ is input. Any hour of the energy model occupancy schedule that is 0.1 or greater will be considered occupied. If no schedule_ is input, all hours of the outdoors are considered occupied.
model [Required]
A Honeybee Model for which UTCI comfort will be mapped. Note that this model should have radiance grids assigned to it in order to produce meaningful results.
epw [Required]
Path to an EPW weather file to be used for the comfort map simulation.
ddy
Path to a DDY file with design days to be used for the initial sizing calculation of the energy simulation. Providing this input is important when there are conditioned Room geometries in the model, in which case the sizing of the building heating/cooling systems is important for modeling the heat exchange between indoors and outdoors. Otherwise, it can be ignored with little consequence for the simulation.
north
A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. This can also be Vector for the direction to North. (Default: 0).
run_period
An AnalysisPeriod to set the start and end dates of the simulation. If None, the simulation will be annual.
wind_speed
A single number for meteorological wind speed in m/s or an hourly data collection of wind speeds that align with the input run_period_. This will be used for all outdoor comfort evaluation. This can also be the path to a folder with csv files that align with the model sensor grids. Each csv file should have the same name as the sensor grid. Each csv file should contain a matrix of air speed values in m/s with one row per sensor and one column per timestep of the run period. Note that, when using this type of matrix input, these values are not meteorological and should be AT HUMAN SUBJECT LEVEL. If unspecified, the EPW wind speed will be used for all outdoor sensors and all sensors on the indoors will use a wind speed of 0.5 m/s, which is the lowest acceptable value for the UTCI model.
schedule
A schedule to specify the relevant times during which comfort should be evaluated. This must either be a Ladybug Hourly Data Collection that aligns with the input run_period_ or the path to a CSV file with a number of rows equal to the length of the run_period_. If unspecified, it will be assumed that all times are relevant for outdoor sensors and the energy model occupancy schedules will be used for indoor sensors.
comfort_par
Optional comfort parameters from the "LB UTCI Comfort Parameters" component to specify the temperatures (in Celcius) that are considered acceptable/comfortable. The default will assume a that the comfort range is between 9C and 26C.
solar_body_par
Optional solar body parameters from the "LB Solar Body Parameters" object to specify the properties of the human geometry assumed in the shortwave MRT calculation. The default assumes average skin/clothing absorptivity and a human subject always has their back to the sun at a 45-degree angle (SHARP = 135).
radiance_par
Text for the radiance parameters to be used for ray tracing. (Default: -ab 2 -ad 5000 -lw 2e-05).
run_settings
Settings from the "HB Recipe Settings" component that specify how the recipe should be run. This can also be a text string of recipe settings.
run [Required]
Set to True to run the recipe and get results. This input can also be the integer "2" to run the recipe silently.
report
Reports, errors, warnings, etc.
env_conds
A folder containing CSV matrices with all of the environmental conditions that were input to the comfort model. These can be loaded into Grasshopper using the "HB Read Environment Matrix" component. This includes the following.
utci
A folder containing CSV maps of Universal Thermal Climate Index (UTCI) temperatures for each sensor grid at each time step of the analysis. This can be connected to the "HB Read Thermal Matrix" component to parse detailed results into Grasshopper. Values are in Celsius.
condition
A folder containing CSV maps of comfort conditions for each sensor grid at each time step of the analysis. This can be connected to the "HB Read Thermal Matrix" component to parse detailed results into Grasshopper. Values are as follows.
category
A folder containing CSV maps of the heat/cold stress categories for each sensor grid at each time step of the analysis. This can be connected to the "HB Read Thermal Matrix" component to parse detailed results into Grasshopper. This can be used to understand not just whether conditions are acceptable but how uncomfortably hot or cold they are. Values indicate the following.
TCP
Lists of values between 0 and 100 for the Thermal Comfort Percent (TCP). These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize spatial thermal comfort. TCP is the percentage of occupied time where thermal conditions are acceptable/comfortable. Occupied hours are determined from the occuppancy schedules of each room (any time where the occupancy schedule is >= 0.1 will be considered occupied). Outdoor sensors are considered occupied at all times. More custom TCP studies can be done by post-processing the condition results.
HSP
Lists of values between 0 and 100 for the Heat Sensation Percent (HSP). These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize uncomfortably hot locations. HSP is the percentage of occupied time where thermal conditions are hotter than what is considered acceptable/comfortable. Occupied hours are determined from the occuppancy schedules of each room (any time where the occupancy schedule is >= 0.1 will be considered occupied). Outdoor sensors are considered occupied at all times. More custom HSP studies can be done by post-processing the condition results.
CSP
Lists of values between 0 and 100 for the Cold Sensation Percent (CSP). These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize uncomfortably cold locations. CSP is the percentage of occupied time where thermal conditions are colder than what is considered acceptable/comfortable. Occupied hours are determined from the occuppancy schedules of each room (any time where the occupancy schedule is >= 0.1 will be considered occupied). Outdoor sensors are considered occupied at all times. More custom CSP studies can be done by post-processing the condition results.
Parse electricity generation results from an energy simulation SQL result file.
sql [Required]
The file path of the SQL result file that has been generated from an energy simulation.
site_totals
Two numbers indicating the following energy values in kWh.
utility_totals
Three numbers indicating the following energy values in kWh.
production
A data collection of all on-site produced electricity (kWh). This represents the alternating current (AC) electricity coming out of the inverter that processes all on-site power production.
consumption
A data collection of all on-site consumed electricity (kWh). This represents the electrcicity consumed by all heating, cooling, lighting equipment, fans, pumps, process loads, and water heaters. All of this consumed electricity is assumed to be alternating current (AC).
dc_power
A list of data collections for the direct current (DC) electricity produced by each on-site electricity generator (kWh). Each photovoltaic object will have a separate data collection.
Parse an .rdd file from an energy simulation to show all possible outputs that can be requested from the simulation.
rdd [Required]
Full path to a RDD file that was generated by EnergyPlus.
keywords
An optional list of keywords that will be used to filter the output names.
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
A list of EnergyPlus output names as strings (eg. 'Surface Window System Solar Transmittance'). If no keywords are input, this will be a list of all possible outputs that can be requested from the simulation. Outputs can be requested from the simulation by plugging them into the outputnames of the "HB Custom Simulation Output" component.
Compute spatially-resolved operative temperature and Adaptive thermal comfort from a Honeybee model.
This recipe uses EnergyPlus to obtain surface temperatures and indoor air temperatures + humidities. Outdoor air temperatures, relative humidities, and air speeds are taken directly from the EPW. The energy properties of the model geometry are what determine the outcome of the simulation, though the model's Radiance sensor grids are what determine where the comfort mapping occurs.
Longwave radiant temperatures are obtained by computing spherical view factors from each sensor to the Room surfaces of the model using Radiance. These view factors are then multiplied by the surface temperatures output by EnergyPlus to yield longwave MRT at each sensor. All indoor shades (eg. those representing furniture) are assumed to be at the room-average MRT.
A Radiance-based enhanced 2-phase method is used for all shortwave MRT calculations, which precisely represents direct sun by tracing a ray from each sensor to the solar position. To determine Thermal Comfort Percent (TCP), the occupancy schedules of the energy model are used. Any hour of the occupancy schedule that is 0.1 or greater will be considered occupied. All hours of the outdoors are considered occupied.
model [Required]
A Honeybee Model for which adaptive comfort will be mapped. Note that this model should have radiance grids assigned to it in order to produce meaningful results.
epw [Required]
Path to an EPW weather file to be used for the comfort map simulation.
ddy [Required]
Path to a DDY file with design days to be used for the initial sizing calculation of the energy simulation.
north
A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. This can also be Vector for the direction to North. (Default: 0).
run_period
An AnalysisPeriod to set the start and end dates of the simulation. If None, the simulation will be annual.
add_str
THIS OPTION IS FOR ADVANCED USERS OF ENERGYPLUS. You can input additional text strings here to be appended to the IDF before energy simulation. The input should be complete EnergyPlus objects following the IDF format. This input can be used to write objects into the IDF that are not currently supported by Honeybee.
air_speed
A single number for air speed in m/s or an hourly data collection of air speeds that align with the input run_period_. This will be used for all indoor comfort evaluation. Note that the EPW wind speed will be used for any outdoor sensors. (Default: 0.1).
comfort_par
Optional comfort parameters from the "LB Adaptive Comfort Parameters" component to specify the criteria under which conditions are considered acceptable/comfortable. The default will use ASHRAE-55 adaptive comfort criteria.
solar_body_par
Optional solar body parameters from the "LB Solar Body Parameters" object to specify the properties of the human geometry assumed in the shortwave MRT calculation. The default assumes average skin/clothing absorptivity and a human subject always has their back to the sun at a 45-degree angle (SHARP = 135).
radiance_par
Text for the radiance parameters to be used for ray tracing. (Default: -ab 2 -ad 5000 -lw 2e-05).
run_settings
Settings from the "HB Recipe Settings" component that specify how the recipe should be run. This can also be a text string of recipe settings.
run [Required]
Set to True to run the recipe and get results. This input can also be the integer "2" to run the recipe silently.
report
Reports, errors, warnings, etc.
env_conds
A folder containing CSV matrices with all of the environmental conditions that were input to the comfort model. These can be loaded into Grasshopper using the "HB Read Environment Matrix" component. This includes the following.
op_temp
A folder containing CSV maps of Operative Temperature for each sensor grid at each time step of the analysis. This can be connected to the "HB Read Thermal Matrix" component to parse detailed results into Grasshopper. Values are in Celsius.
condition
A folder containing CSV maps of comfort conditions for each sensor grid at each time step of the analysis. This can be connected to the "HB Read Thermal Matrix" component to parse detailed results into Grasshopper. Values are as follows.
deg_neut
A folder containing CSV maps of the degrees Celsius from the adaptive comfort neutral temperature for each sensor grid at each time step of the analysis. This can be connected to the "HB Read Thermal Matrix" component to parse detailed results into Grasshopper. This can be used to understand not just whether conditions are acceptable but how uncomfortably hot or cold they are.
TCP
Lists of values between 0 and 100 for the Thermal Comfort Percent (TCP). These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize spatial thermal comfort. TCP is the percentage of occupied time where thermal conditions are acceptable/comfortable. Occupied hours are determined from the occupancy schedules of each room (any time where the occupancy schedule is >= 0.1 will be considered occupied). Outdoor sensors are considered occupied at all times. More custom TCP studies can be done by post-processing the condition results.
HSP
Lists of values between 0 and 100 for the Heat Sensation Percent (HSP). These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize uncomfortably hot locations. HSP is the percentage of occupied time where thermal conditions are hotter than what is considered acceptable/comfortable. Occupied hours are determined from the occupancy schedules of each room (any time where the occupancy schedule is >= 0.1 will be considered occupied). Outdoor sensors are considered occupied at all times. More custom HSP studies can be done by post-processing the condition results.
CSP
Lists of values between 0 and 100 for the Cold Sensation Percent (CSP). These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize uncomfortably cold locations. CSP is the percentage of occupied time where thermal conditions are colder than what is considered acceptable/comfortable. Occupied hours are determined from the occupancy schedules of each room (any time where the occupancy schedule is >= 0.1 will be considered occupied). Outdoor sensors are considered occupied at all times. More custom CSP studies can be done by post-processing the condition results.
Compute spatially-resolved operative temperature and Predicted Mean Vote (PMV) thermal comfort from a Honeybee model. This recipe can also (optionally) compute Standard Effective Temperature (SET).
This recipe uses EnergyPlus to obtain surface temperatures and indoor air temperatures + humidities. Outdoor air temperatures, relative humidities, and air speeds are taken directly from the EPW. The energy properties of the model geometry are what determine the outcome of the simulation, though the model's Radiance sensor grids are what determine where the comfort mapping occurs.
Longwave radiant temperatures are obtained by computing spherical view factors from each sensor to the Room surfaces of the model using Radiance. These view factors are then multiplied by the surface temperatures output by EnergyPlus to yield longwave MRT at each sensor. All indoor shades (eg. those representing furniture) are assumed to be at the room-average MRT.
A Radiance-based enhanced 2-phase method is used for all shortwave MRT calculations, which precisely represents direct sun by tracing a ray from each sensor to the solar position. To determine Thermal Comfort Percent (TCP), the occupancy schedules of the energy model are used. Any hour of the occupancy schedule that is 0.1 or greater will be considered occupied. All hours of the outdoors are considered occupied.
model [Required]
A Honeybee Model for which PMV comfort will be mapped. Note that this model should have radiance grids assigned to it in order to produce meaningful results.
epw [Required]
Path to an EPW weather file to be used for the comfort map simulation.
ddy [Required]
Path to a DDY file with design days to be used for the initial sizing calculation of the energy simulation.
north
A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. This can also be Vector for the direction to North. (Default: 0).
run_period
An AnalysisPeriod to set the start and end dates of the simulation. If None, the simulation will be annual.
add_str
THIS OPTION IS FOR ADVANCED USERS OF ENERGYPLUS. You can input additional text strings here to be appended to the IDF before energy simulation. The input should be complete EnergyPlus objects following the IDF format. This input can be used to write objects into the IDF that are not currently supported by Honeybee.
write_set_map
A boolean to note whether the output temperature CSV should record Operative Temperature or Standard Effective Temperature (SET). SET is relatively intense to compute and so only recording Operative Temperature can greatly reduce run time, particularly when air speeds are low. However, SET accounts for all 6 PMV model inputs and so is a more representative "feels-like" temperature for the PMV model.
air_speed
A single number for air speed in m/s or an hourly data collection of air speeds that align with the input run_period_. This will be used for all indoor comfort evaluation. Note that the EPW wind speed will be used for any outdoor sensors. (Default: 0.1).
met_rate
A single number for metabolic rate in met or an hourly data collection of met rates that align with the run_period_. (Default: 1.1, for seated, typing).
clo_value
A single number for clothing level in clo or an hourly data collection of clothing levels that align with the run_period_. (Default: 0.7, for pants and a long sleeve shirt).
comfort_par
Optional comfort parameters from the "LB PMV Comfort Parameters" component to specify the criteria under which conditions are considered acceptable/comfortable. The default will assume a PPD threshold of 10% and no absolute humidity constraints.
solar_body_par
Optional solar body parameters from the "LB Solar Body Parameters" object to specify the properties of the human geometry assumed in the shortwave MRT calculation. The default assumes average skin/clothing absorptivity and a human subject always has their back to the sun at a 45-degree angle (SHARP = 135).
radiance_par
Text for the radiance parameters to be used for ray tracing. (Default: -ab 2 -ad 5000 -lw 2e-05).
run_settings
Settings from the "HB Recipe Settings" component that specify how the recipe should be run. This can also be a text string of recipe settings.
run [Required]
Set to True to run the recipe and get results. This input can also be the integer "2" to run the recipe silently.
report
Reports, errors, warnings, etc.
env_conds
A folder containing CSV matrices with all of the environmental conditions that were input to the comfort model. These can be loaded into Grasshopper using the "HB Read Environment Matrix" component. This includes the following.
temperature
A folder containing CSV maps of Operative Temperature for each sensor grid at each time step of the analysis. Alternatively, if the write_set_map_ option is used, the CSV maps here will contain Standard Effective Temperature (SET). This can be connected to the "HB Read Thermal Matrix" component to parse detailed results into Grasshopper. Values are in Celsius.
condition
A folder containing CSV maps of comfort conditions for each sensor grid at each time step of the analysis. This can be connected to the "HB Read Thermal Matrix" component to parse detailed results into Grasshopper. Values are as follows.
pmv
A folder containing CSV maps of the Predicted Mean Vote (PMV) for each sensor grid at each time step of the analysis. This can be connected to the "HB Read Thermal Matrix" component to parse detailed results into Grasshopper. This can be used to understand not just whether conditions are acceptable but how uncomfortably hot or cold they are.
TCP
Lists of values between 0 and 100 for the Thermal Comfort Percent (TCP). These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize spatial thermal comfort. TCP is the percentage of occupied time where thermal conditions are acceptable/comfortable. Occupied hours are determined from the occupancy schedules of each room (any time where the occupancy schedule is >= 0.1 will be considered occupied). Outdoor sensors are considered occupied at all times. More custom TCP studies can be done by post-processing the condition results.
HSP
Lists of values between 0 and 100 for the Heat Sensation Percent (HSP). These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize uncomfortably hot locations. HSP is the percentage of occupied time where thermal conditions are hotter than what is considered acceptable/comfortable. Occupied hours are determined from the occupancy schedules of each room (any time where the occupancy schedule is >= 0.1 will be considered occupied). Outdoor sensors are considered occupied at all times. More custom HSP studies can be done by post-processing the condition results.
CSP
Lists of values between 0 and 100 for the Cold Sensation Percent (CSP). These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize uncomfortably cold locations. CSP is the percentage of occupied time where thermal conditions are colder than what is considered acceptable/comfortable. Occupied hours are determined from the occupancy schedules of each room (any time where the occupancy schedule is >= 0.1 will be considered occupied). Outdoor sensors are considered occupied at all times. More custom CSP studies can be done by post-processing the condition results.
Read the detailed results of a thermal mapping analysis from a folder of CSV files output by a thermal mapping component.
Detailed results include temperature amd thermal condition results. It also includes metrics that give a sense of how hot or cold condition are like pmv, utci category, or adaptive comfort degrees from neutral temperature.
comf_result [Required]
Path to a folder containing CSV files output by a thermal mapping component.
load [Required]
Set to True to load the data from the CSV files into Grasshopper.
comf_mtx
A Matrix object that can be connected to the "HB Visualize Thermal Map" component in order to spatially visualize results. This Matrix object can also be connected to the "LB Deconstruct Matrix" component to obtain detailed point-by-point and hour-by-hour values.
When deconstructed, each sub-list of the matrix (aka. branch of the Data Tree) represents one of the sensor grids used for analysis. The length of each sub-list matches the number of points in the grid. Each value in the sub-list is an hourly data collection containing hour-by-hour results for each point.
Spatially visualize the detailed results of a thermal mapping analysis from a comfort matrix.
comf_mtx [Required]
A comfort Matrix object from the "HB Read Thermal Matrix" component.
mesh [Required]
Mesh objects that correspond with the sensor grids of the thermal map analysis. These will be , with a number of faces or vertices that match the number of input values and will be colored with results.
sim_step
An optional integer (greater than or equal to 0) to select a specific time step of the comfort results to be displayed. Note that this will override any connected period.
period
A Ladybug analysis period to be applied to select a slice of time across the comfort results to be displayed.
legend_par
An optional LegendParameter object to change the display of the results.
report
...
mesh
The input mesh objects colored with results.
legend
Geometry representing the legend for the results.
title
A text object for the title.
colors
The colors associated with each input value.
values
A list of numbers for each face of the mesh, which are used to generate the colors.
Read the detailed environmental conditions of a thermal mapping analysis from the env_conds output by a thermal mapping component.
Environemntal conditions include raw inputs to the thermal comfort model, such as air temperature, MRT, longwave MRT, and shortwave MRT delta.
env_conds [Required]
Path to a folder containing the detailed environmental conditions output by a thermal mapping component.
metric
Text or an integer for the specific metric to be loaded from the environmental conditions. (Default: MRT). Choose from the following.
load [Required]
Set to True to load the data into Grasshopper.
comf_mtx
A Matrix object that can be connected to the "HB Visualize Thermal Map" component in order to spatially visualize results. This Matrix object can also be connected to the "LB Deconstruct Matrix" component to obtain detailed point-by-point and hour-by-hour values. When deconstructed, each sub-list of the matrix (aka. branch of the Data Tree) represents one of the sensor grids used for analysis. The length of each sub-list matches the number of points in the grid. Each value in the sub-list is an hourly data collection containing hour-by-hour results for each point.
Deconstruct a construction set into its constituient interior constructions.
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.
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.
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.
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.
hb_objs
The input honeybee objects with their constructions edited.
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.
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).
mat
A window material that describes a single glass pane and can be assigned to a Honeybee Window construction.
Create a standard opaque material, which can be plugged into the "HB Opaque Construction" component.
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.
mat
A standard opaque material that can be assigned to a Honeybee Opaque construction.
Get information about carbon emission intensity (CEI) from an EnergyPlus SQL file.
The location and year (or input emissions of electricity intensity) will be used to compute carbon intensity for both electricity and district heating/cooling. Fixed numbers will be used to convert the following on-site fuel sources:
Natural Gas -- 277.358 kg/MWh * Propane -- 323.897 kg/MWh * Fuel Oil -- 294.962 kg/MWh
sql [Required]
The file path of the SQL result file that has been generated from an energy simulation. This can also be a list of EnergyPlus files in which case EUI will be computed across all files. Lastly, it can be a directory or list of directories containing results, in which case, EUI will be calculated form all files ending in .sql.
loc_kgMWh [Required]
A ladybug Location object in the USA, which will be used to determine the subregion of the electrical grid. Alternatively, it can be A number for the electric grid carbon emissions in kg CO2/MWh. The following rules of thumb may be used as a guide:
year
An integer for the future year for which carbon emissions will be estimated. Values must be an even number and be between 2020 and 2050. (Default: 2030).
cei
A number for the total annual carbon emission intensity (CEI). This is the sum of all operational carbon emissions divided by the gross floor area (including both conditioned and unconditioned spaces). Units are kg CO2/m2.
cei_end_use
The carbon emission intensity broken down by each end use. These values coorespond to the end_uses output below. Values are in kg CO2/m2 .
end_uses
A list of text for each of the end uses in the simulation (Heating, Cooling, etc.). Thes outputs coorespond to the eui_end_use output above.
gross_floor
The total gross floor area of the energy model. This can be used to compute the total energy use from the intensity values above or it can be used to help with other result post-processing. The value will be in m2 if ip_ is False or None and ft2 if True.
-
Parse a zone sizing (ZSZ) csv result file from an energy simulation to get data collections for the cooling/heating load over the peak design day.
zsz [Required]
Full path to a zone sizing (ZSZ) csv result file that was generated by EnergyPlus.
cooling_load
a list of HourlyContinuousCollections for zone cooling load. There will be one data collection per conditioned zone in the model.
heating_load
a list of HourlyContinuousCollections for zone heating load. There will be one data collection per conditioned zone in the model.