honeybee.model module

Honeybee Model.

class honeybee.model.Model(identifier, rooms=None, orphaned_faces=None, orphaned_shades=None, orphaned_apertures=None, orphaned_doors=None, shade_meshes=None, units='Meters', tolerance=None, angle_tolerance=1.0)

Bases: _Base

A collection of Rooms, Faces, Shades, Apertures, and Doors representing a model.

Parameters

• identifier – Text string for a unique Model ID. Must be < 100 characters and not contain any spaces or special characters.

• rooms – A list of Room objects in the model.

• orphaned_faces – A list of the Face objects in the model that lack a parent Room. Note that orphaned Faces are translated to sun-blocking shade objects in energy simulation.

• orphaned_shades – A list of the Shade objects in the model that lack a parent.

• orphaned_apertures – A list of the Aperture objects in the model that lack a parent Face. Note that orphaned Apertures are translated to sun-blocking shade objects in energy simulation.

• orphaned_doors – A list of the Door objects in the model that lack a parent Face. Note that orphaned Doors are translated to sun-blocking shade objects in energy simulation.

• shade_meshes – A list of the ShadeMesh objects in the model.

• units –

  Text for the units system in which the model geometry exists. Default: ‘Meters’. Choose from the following:

  • Meters

  • Millimeters

  • Feet

  • Inches

  • Centimeters

• tolerance – The maximum difference between x, y, and z values at which vertices are considered equivalent. Zero indicates that no tolerance checks should be performed. None indicates that the tolerance will be set based on the units above, with the tolerance consistently being between 1 cm and 1 mm (roughly the tolerance implicit in the OpenStudio SDK and EnergyPlus). (Default: None).

• angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. Zero indicates that no angle tolerance checks should be performed. (Default: 1.0).

Properties:

• identifier

• display_name

• units

• tolerance

• angle_tolerance

• rooms

• faces

• apertures

• doors

• shades

• shade_meshes

• indoor_shades

• outdoor_shades

• orphaned_faces

• orphaned_shades

• orphaned_apertures

• orphaned_doors

• stories

• volume

• floor_area

• exposed_area

• exterior_wall_area

• exterior_roof_area

• exterior_aperture_area

• exterior_wall_aperture_area

• exterior_skylight_aperture_area

• min

• max

• top_level_dict

• user_data

ToString()

Overwrite .NET ToString.

add_aperture(obj)

Add an orphaned Aperture object to the model.

add_apertures(objs)

Add a list of orphaned Aperture objects to the model.

add_door(obj)

Add an orphaned Door object to the model.

add_doors(objs)

Add a list of orphaned Door objects to the model.

add_face(obj)

Add an orphaned Face object without a parent to the model.

add_faces(objs)

Add a list of orphaned Face objects to the model.

add_model(other_model)

Add another Model object to this model.

add_prefix(prefix)

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

This is particularly useful in workflows where you duplicate and edit a starting object and then want to combine it with the original object since all objects within a Model must have unique identifiers.

Parameters

prefix – Text that will be inserted at the start of this object’s (and child objects’) identifier and display_name. It is recommended that this prefix be short to avoid maxing out the 100 allowable characters for honeybee identifiers.

add_room(obj)

Add a Room object to the model.

add_rooms(objs)

Add a list of Room objects to the model.

add_shade(obj)

Add an orphaned Shade object to the model, typically representing context.

add_shade_mesh(obj)

Add a ShadeMesh object to the model.

add_shade_meshes(objs)

Add a list of ShadeMesh objects to the model.

add_shades(objs)

Add a list of orphaned Shade objects to the model.

apertures_by_identifier(identifiers)

Get a list of Aperture objects in the model given the Aperture identifiers.

assign_stories_by_floor_height(min_difference=2.0, overwrite=False)

Assign story properties to the rooms of this Model using their floor heights.

Stories will be named with a standard convention (‘Floor1’, ‘Floor2’, etc.).

Parameters

• min_difference – An float value to denote the minimum difference in floor heights that is considered meaningful. This can be used to ensure rooms like those representing stair landings are grouped with floors. Default: 2.0, which means that any difference in floor heights less than 2.0 will be considered a part of the same story. This assumption is suitable for models in meters.

• overwrite – If True, all story properties of this model’s rooms will be overwritten by this method. If False, this method will only assign stories to Rooms that do not already have a story identifier already assigned to them. (Default: False).

Returns

A list of the unique story names that were assigned to the input rooms.

check_all(raise_exception=True, detailed=False)

Check all of the aspects of the Model for possible errors.

This includes basic properties like adjacency checks and all geometry checks. Furthermore, all extension attributes will be checked assuming the extension Model properties have a check_all function. Note that an exception will always be raised if the model has a tolerance of zero as this means that no geometry checks can be performed.

Parameters

• raise_exception – Boolean to note whether a ValueError should be raised if any Model errors are found. If False, this method will simply return a text string with all errors that were found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A text string with all errors that were found or a list if detailed is True. This string (or list) will be empty if no errors were found.

check_all_air_boundaries_adjacent(raise_exception=True, detailed=False)

Check that all Faces with the AirBoundary type are adjacent to other Faces.

This is a requirement for energy simulation.

Parameters

• raise_exception – Boolean to note whether a ValueError should be raised if an AirBoundary without an adjacency is found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_degenerate_rooms(tolerance=None, raise_exception=True, detailed=False)

Check whether there are degenerate Rooms (with zero volume) within the Model.

Parameters

• tolerance – The maximum difference between x, y, and z values at which face vertices are considered equivalent. If None, the Model tolerance will be used. (Default: None).

• raise_exception – Boolean to note whether a ValueError should be raised if degenerate Rooms are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_duplicate_face_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate Face identifiers in the model.

Parameters

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_duplicate_room_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate Room identifiers in the model.

Parameters

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_duplicate_shade_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate Shade identifiers in the model.

Parameters

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_duplicate_shade_mesh_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate ShadeMesh identifiers in the model.

Parameters

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_duplicate_sub_face_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate sub-face identifiers in the model.

Note that both Apertures and Doors are checked for duplicates since the two are counted together by EnergyPlus.

Parameters

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_matching_adjacent_areas(tolerance=None, raise_exception=True, detailed=False)

Check that all adjacent Faces have areas that match within the tolerance.

This is required for energy simulation in order to get matching heat flow across adjacent Faces. Otherwise, conservation of energy is violated. Note that, if there are missing adjacencies in the model, the message from this method will simply note this fact without reporting on mis-matched areas.

Parameters

• tolerance – tolerance: The maximum difference between x, y, and z values at which face vertices are considered equivalent. If None, the Model tolerance will be used. (Default: None).

• raise_exception – Boolean to note whether a ValueError should be raised if invalid adjacencies are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_missing_adjacencies(raise_exception=True, detailed=False)

Check that all Faces Apertures, and Doors have adjacent objects in the model.

Parameters

• raise_exception – Boolean to note whether a ValueError should be raised if invalid adjacencies are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_planar(tolerance=None, raise_exception=True, detailed=False)

Check that all of the Model’s geometry components are planar.

This includes all of the Model’s Faces, Apertures, Doors and Shades.

Parameters

• tolerance – The minimum distance between a given vertex and a the object’s plane at which the vertex is said to lie in the plane. If None, the Model tolerance will be used. (Default: None).

• raise_exception – Boolean to note whether an ValueError should be raised if a vertex does not lie within the object’s plane.

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_room_volume_collisions(tolerance=None, raise_exception=True, detailed=False)

Check whether the Model’s rooms collide with one another beyond the tolerance.

Parameters

• tolerance – tolerance: The maximum difference between x, y, and z values at which face vertices are considered equivalent. If None, the Model tolerance will be used. (Default: None).

• raise_exception – Boolean to note whether a ValueError should be raised if the room geometry does not form a closed solid. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_rooms_solid(tolerance=None, angle_tolerance=None, raise_exception=True, detailed=False)

Check whether the Model’s rooms are closed solid to within tolerances.

Parameters

• tolerance – tolerance: The maximum difference between x, y, and z values at which face vertices are considered equivalent. If None, the Model tolerance will be used. (Default: None).

• angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. If None, the Model angle_tolerance will be used. (Default: None).

• raise_exception – Boolean to note whether a ValueError should be raised if the room geometry does not form a closed solid. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_self_intersecting(tolerance=None, raise_exception=True, detailed=False)

Check that no edges of the Model’s geometry components self-intersect.

This includes all of the Model’s Faces, Apertures, Doors and Shades.

Parameters

• tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered equivalent. If None, the Model tolerance will be used. (Default: None).

• raise_exception – If True, a ValueError will be raised if an object intersects with itself (like a bowtie). (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_sub_faces_overlapping(tolerance=None, raise_exception=True, detailed=False)

Check that model’s sub-faces do not overlap with one another.

Parameters

• tolerance – The minimum distance that two sub-faces must overlap in order for them to be considered overlapping and invalid. If None, the Model tolerance will be used. (Default: None).

• raise_exception – Boolean to note whether a ValueError should be raised if a sub-faces overlap with one another.

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_sub_faces_valid(tolerance=None, angle_tolerance=None, raise_exception=True, detailed=False)

Check that model’s sub-faces are co-planar with faces and in their boundary.

Note this does not check the planarity of the sub-faces themselves, whether they self-intersect, or whether they have a non-zero area.

Parameters

• tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered equivalent. If None, the Model tolerance will be used. (Default: None).

• angle_tolerance – The max angle in degrees that the plane normals can differ from one another in order for them to be considered coplanar. If None, the Model angle_tolerance will be used. (Default: None).

• raise_exception – Boolean to note whether a ValueError should be raised if an sub-face is not valid. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

check_upside_down_faces(angle_tolerance=None, raise_exception=True, detailed=False)

Check that the Model’s Faces have the correct direction for the face type.

This method will only report Floors that are pointing upwards or RoofCeilings that are pointed downwards. These cases are likely modeling errors and are in danger of having their vertices flipped by EnergyPlus, causing them to not see the sun.

Parameters

• angle_tolerance – The max angle in degrees that the Face normal can differ from up or down before it is considered a case of a downward pointing RoofCeiling or upward pointing Floor. If None, it will be the model angle tolerance. (Default: None).

• raise_exception – Boolean to note whether an ValueError should be raised if the Face is an an upward pointing Floor or a downward pointing RoofCeiling.

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

A string with the message or a list with a dictionary if detailed is True.

comparison_report(other_model, ignore_deleted=False, ignore_added=False)

Get a dictionary outlining the differences between this model and another.

The resulting dictionary will only report top-level objects that are different between this model and the other. If an object has not changed at all, then it will not show up in the report.

Changes to geometry are reported separately from changes in metadata (aka. properties) for each of the top level objects.

If the Model units or tolerance are different between the two models, then the units and tolerance of this model will take precedence and the other_model will be converted to these units and tolerance for geometry comparison.

Parameters

• other_model – A new Model to which this current model will be compared.

• ignore_deleted – A boolean to note whether objects that appear in this current model but not in the other model should be reported. It is useful to set this to True when the other model represents only a subset of the current model. (Default: False).

• ignore_added – A boolean to note whether objects that appear in the other model but not in the current model should be reported. (Default: False).

Returns

A dictionary of differences between this model and the other model in the format below.

static conversion_factor_to_meters(units)

Get the conversion factor to meters based on input units.

Parameters

units –

Text for the units. Choose from the following:

• Meters

• Millimeters

• Feet

• Inches

• Centimeters

Returns

A number for the conversion factor, which should be multiplied by all distance units taken from Rhino geometry in order to convert them to meters.

convert_to_units(units='Meters')

Convert all of the geometry in this model to certain units.

This involves scaling the geometry, scaling the Model tolerance, and changing the Model’s units property.

Parameters

units –

Text for the units to which the Model geometry should be converted. Default: Meters. Choose from the following:

• Meters

• Millimeters

• Feet

• Inches

• Centimeters

display_dict()

Get a list of DisplayFace3D dictionaries for visualizing the object.

doors_by_identifier(identifiers)

Get a list of Door objects in the model given the Door identifiers.

duplicate()

Get a copy of this object.

faces_by_identifier(identifiers)

Get a list of Face objects in the model given the Face identifiers.

classmethod from_dict(data)

Initialize a Model from a dictionary.

Parameters

data – A dictionary representation of a Model object.

classmethod from_file(hb_file)

Initialize a Model from a HBJSON or HBpkl file, auto-sensing the type.

Parameters

hb_file – Path to either a HBJSON or HBpkl file.

classmethod from_hbjson(hbjson_file)

Initialize a Model from a HBJSON file.

Parameters

hbjson_file – Path to HBJSON file.

classmethod from_hbpkl(hbpkl_file)

Initialize a Model from a HBpkl file.

Parameters

hbpkl_file – Path to HBpkl file.

classmethod from_l_shaped_plan(width_1, length_1, width_2, length_2, floor_to_floor_height, perimeter_offset=0, story_count=1, orientation_angle=0, outdoor_roof=True, ground_floor=True, units='Meters', tolerance=None, angle_tolerance=1.0)

Create a model with an L-shaped floor plan.

Note that the resulting Rooms in the model won’t have any windows or solved adjacencies. These can be added by using the Model.solve_adjacency method and the various Face.apertures_by_XXX methods.

Parameters

• width_1 – Number for the width of the lower part of the L segment.

• length_1 – Number for the length of the lower part of the L segment, not counting the overlap between the upper and lower segments.

• width_2 – Number for the width of the upper (left) part of the L segment.

• length_2 – Number for the length of the upper (left) part of the L segment, not counting the overlap between the upper and lower segments.

• floor_to_floor_height – Number for the height of each floor of the model (in the Z direction).

• perimeter_offset – An optional positive number that will be used to offset the perimeter to create core/perimeter Rooms. If this value is 0, no offset will occur and each floor will have one Room. (Default: 0).

• story_count – An integer for the number of stories to generate. (Default: 1).

• orientation_angle – A number between 0 and 360 for the counterclockwise orientation that the width of the box faces. (0=North, 90=East, 180=South, 270=West). (Default: 0).

• outdoor_roof – Boolean to note whether the roof faces of the top floor should be outdoor or adiabatic. (Default: True).

• ground_floor – Boolean to note whether the floor faces of the bottom floor should be ground or adiabatic. (Default: True).

• units – Text for the units system in which the model geometry exists. (Default: ‘Meters’).

• tolerance – The maximum difference between x, y, and z values at which vertices are considered equivalent. Zero indicates that no tolerance checks should be performed. None indicates that the tolerance will be set based on the units above, with the tolerance consistently being between 1 cm and 1 mm (roughly the tolerance implicit in the OpenStudio SDK and EnergyPlus). (Default: None).

• angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. Zero indicates that no angle tolerance checks should be performed. (Default: 1.0).

classmethod from_objects(identifier, objects, units='Meters', tolerance=None, angle_tolerance=1.0)

Initialize a Model from a list of any type of honeybee-core geometry objects.

Parameters

• identifier – Text string for a unique Model ID. Must be < 100 characters and not contain any spaces or special characters.

• objects – A list of honeybee Rooms, Faces, Shades, ShadeMEshes, Apertures and Doors.

• units –

  Text for the units system in which the model geometry exists. Default: ‘Meters’. Choose from the following:

  • Meters

  • Millimeters

  • Feet

  • Inches

  • Centimeters

• tolerance – The maximum difference between x, y, and z values at which vertices are considered equivalent. Zero indicates that no tolerance checks should be performed. None indicates that the tolerance will be set based on the units above, with the tolerance consistently being between 1 cm and 1 mm (roughly the tolerance implicit in the OpenStudio SDK and EnergyPlus). (Default: None).

• angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. Zero indicates that no angle tolerance checks should be performed. (Default: 1.0).

classmethod from_rectangle_plan(width, length, floor_to_floor_height, perimeter_offset=0, story_count=1, orientation_angle=0, outdoor_roof=True, ground_floor=True, units='Meters', tolerance=None, angle_tolerance=1.0)

Create a model with a rectangular floor plan.

Note that the resulting Rooms in the model won’t have any windows or solved adjacencies. These can be added by using the Model.solve_adjacency method and the various Face.apertures_by_XXX methods.

Parameters

• width – Number for the width of the plan (in the X direction).

• length – Number for the length of the plan (in the Y direction).

• floor_to_floor_height – Number for the height of each floor of the model (in the Z direction).

• perimeter_offset – An optional positive number that will be used to offset the perimeter to create core/perimeter Rooms. If this value is 0, no offset will occur and each floor will have one Room. (Default: 0).

• story_count – An integer for the number of stories to generate. (Default: 1).

• orientation_angle – A number between 0 and 360 for the counterclockwise orientation that the width of the box faces. (0=North, 90=East, 180=South, 270=West). (Default: 0).

• outdoor_roof – Boolean to note whether the roof faces of the top floor should be outdoor or adiabatic. (Default: True).

• ground_floor – Boolean to note whether the floor faces of the bottom floor should be ground or adiabatic. (Default: True).

• units – Text for the units system in which the model geometry exists. (Default: ‘Meters’).

• tolerance – The maximum difference between x, y, and z values at which vertices are considered equivalent. Zero indicates that no tolerance checks should be performed. None indicates that the tolerance will be set based on the units above, with the tolerance consistently being between 1 cm and 1 mm (roughly the tolerance implicit in the OpenStudio SDK and EnergyPlus). (Default: None).

• angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. Zero indicates that no angle tolerance checks should be performed. (Default: 1.0).

classmethod from_shoe_box(width, depth, height, orientation_angle=0, window_ratio=0, adiabatic=True, units='Meters', tolerance=None, angle_tolerance=1.0)

Create a model with a single shoe box Room.

Parameters

• width – Number for the width of the box (in the X direction).

• depth – Number for the depth of the box (in the Y direction).

• height – Number for the height of the box (in the Z direction).

• orientation_angle – A number between 0 and 360 for the clockwise orientation of the box in degrees. (0=North, 90=East, 180=South, 270=West). (Default: 0).

• window_ratio – A number between 0 and 1 (but not equal to 1) for the ratio between aperture area and area of the face pointing towards the orientation-angle. Using 0 will generate no windows. (Default: 0).

• adiabatic – Boolean to note whether the faces that are not in the direction of the orientation-angle are adiabatic or outdoors. (Default: True)

• units – Text for the units system in which the model geometry exists. (Default: ‘Meters’).

• tolerance – The maximum difference between x, y, and z values at which vertices are considered equivalent. Zero indicates that no tolerance checks should be performed. None indicates that the tolerance will be set based on the units above, with the tolerance consistently being between 1 cm and 1 mm (roughly the tolerance implicit in the OpenStudio SDK and EnergyPlus). (Default: None).

• angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. Zero indicates that no angle tolerance checks should be performed. (Default: 1.0).

classmethod from_stl(file_path, geometry_to_faces=False, units='Meters', tolerance=None, angle_tolerance=1.0)

Create a Honeybee Model from an STL file.

Parameters

• file_path – Path to an STL file as a text string. The STL file can be in either ASCII or binary format.

• geometry_to_faces – A boolean to note whether the geometry in the STL file should be imported as Faces (with Walls/Floors/RoofCeiling set according to the normal). If False, all geometry will be imported as ShadeMeshes instead of Faces. (Default: False).

• units –

  Text for the units system in which the model geometry exists. Default: ‘Meters’. Choose from the following:

  • Meters

  • Millimeters

  • Feet

  • Inches

  • Centimeters

• tolerance – The maximum difference between x, y, and z values at which vertices are considered equivalent. Zero indicates that no tolerance checks should be performed. None indicates that the tolerance will be set based on the units above, with the tolerance consistently being between 1 cm and 1 mm (roughly the tolerance implicit in the OpenStudio SDK and EnergyPlus). (Default: None).

• angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. Zero indicates that no angle tolerance checks should be performed. (Default: 1.0).

classmethod from_sync(base_model, other_model, sync_instructions)

Initialize a Model from two models and instructions for syncing them.

The SyncInstructions dictionary schema is essentially a variant of the ComparisonReport schema that can be obtained by calling base_model.comparison_report(other_model). The main difference is that the XXX_changed properties should be replaced with update_XXX properties for whether the change from the other_model should be accepted into the new model or rejected from it.

Parameters

• base_model – An base Honeybee Model that forms the base of the new model to be created.

• other_model – An other Honeybee Model that contains changes to the base model to be merged into the base_model.

• sync_instructions – A dictionary of SyncInstructions that states which changes from the other_model should be accepted or rejected when building a new Model from the base_model.

classmethod from_sync_files(base_model_file, other_model_file, sync_instructions_file)

Initialize a Model from two model files and instructions for syncing them.

Parameters

• base_model_file – An base Honeybee Model (as HBJSON or HBPkl) that forms the base of the new model to be created.

• other_model_file – An other Honeybee Model (as HBJSON or HBPkl) that contains changes to the base model to be merged into the base_model.

• sync_instructions – A JSON of SyncInstructions that states which changes from the other_model should be accepted or rejected when building a new Model from the base_model. The SyncInstructions schema is essentially a variant of the ComparisonReport schema that can be obtained by calling base_model.comparison_report( other_model). The main difference is that the XXX_changed properties should be replaced with update_XXX properties for whether the change from the other_model should be accepted into the new model or rejected from it.

generate_exterior_aperture_grid(dimension, offset=0.1, aperture_type='All')

Get a gridded Mesh3D offset from the exterior Apertures of this Model.

Will be None if the Model has no exterior Apertures.

Parameters

• dimension – The dimension of the grid cells as a number.

• offset – A number for how far to offset the grid from the base aperture. Positive numbers indicate an offset towards the exterior while negative numbers indicate an offset towards the interior, essentially modeling the value of sun on the building interior. (Default is 0.1, which will offset the grid to be 0.1 unit from the aperture).

• aperture_type –

  Text to specify the type of Aperture that will be used to generate grids. Window indicates Apertures in Walls. Choose from the following. (Default: All).

  • Window

  • Skylight

  • All

generate_exterior_face_grid(dimension, offset=0.1, face_type='Wall', punched_geometry=False)

Get a gridded Mesh3D offset from the exterior Faces of this Model.

This will be None if the Model has no exterior Faces.

Parameters

• dimension – The dimension of the grid cells as a number.

• offset – A number for how far to offset the grid from the base face. Positive numbers indicate an offset towards the exterior. (Default is 0.1, which will offset the grid to be 0.1 unit from the faces).

• face_type –

  Text to specify the type of face that will be used to generate grids. Note that only Faces with Outdoors boundary conditions will be used, meaning that most Floors will typically be excluded unless they represent the underside of a cantilever. Choose from the following. (Default: Wall).

  • Wall

  • Roof

  • Floor

  • All

• punched_geometry – Boolean to note whether the punched_geometry of the faces should be used (True) with the areas of sub-faces removed from the grid or the full geometry should be used (False). (Default:False).

move(moving_vec)

Move this Model along a vector.

Parameters

moving_vec – A ladybug_geometry Vector3D with the direction and distance to move the Model.

rectangularize_apertures(subdivision_distance=None, max_separation=None, merge_all=False, resolve_adjacency=True, tolerance=None, angle_tolerance=None)

Convert all Apertures on this Room to be rectangular.

This is useful when exporting to simulation engines that only accept rectangular window geometry. This method will always result ing Rooms where all Apertures are rectangular. However, if the subdivision_distance is not set, some Apertures may extend past the parent Face or may collide with one another.

Parameters

• subdivision_distance – A number for the resolution at which the non-rectangular Apertures will be subdivided into smaller rectangular units. Specifying a number here ensures that the resulting rectangular Apertures do not extend past the parent Face or collide with one another. If None, all non-rectangular Apertures will be rectangularized by taking the bounding rectangle around the Aperture. (Default: None).

• max_separation – A number for the maximum distance between non-rectangular Apertures at which point the Apertures will be merged into a single rectangular geometry. This is often helpful when there are several triangular Apertures that together make a rectangle when they are merged across their frames. In such cases, this max_separation should be set to a value that is slightly larger than the window frame. If None, no merging of Apertures will happen before they are converted to rectangles. (Default: None).

• merge_all – Boolean to note whether all apertures should be merged before they are rectangularized. If False, only non-rectangular apertures will be merged before rectangularization. Note that this argument has no effect when the max_separation is None. (Default: False).

• resolve_adjacency – Boolean to note whether Room adjacencies should be re-solved after the Apertures have been rectangularized. Setting this to True should ensure that and interior Apertures that are rectangularized retain their Surface boundary conditions. If False, all interior Apertures that have been rectangularized will have an Outdoors boundary condition. (Default: True).

• tolerance – The maximum difference between point values for them to be considered equivalent. If None, the Model tolerance will be used. (Default: None).

• angle_tolerance – The max angle in degrees that the corners of the rectangle can differ from a right angle before it is not considered a rectangle. If None, the Model angle_tolerance will be used. (Default: None).

reflect(plane)

Reflect this Model across a plane with the input normal vector and origin.

Parameters

plane – A ladybug_geometry Plane across which the object will be reflected.

remove_all_apertures()

Remove all Apertures from the model.

This includes assigned apertures as well as orphaned apertures.

remove_all_doors()

Remove all Doors from the model.

This includes assigned doors as well as orphaned doors.

remove_all_shades()

Remove all Shades from the model.

This includes assigned shades as well as orphaned shades.

remove_apertures(aperture_ids=None)

Remove orphaned Apertures from the model.

Parameters

aperture_ids – An optional list of Aperture identifiers to only remove certain apertures from the model. If None, all Apertures will be removed. (Default: None).

remove_assigned_apertures()

Remove all Apertures assigned to the model’s Faces.

This includes nested apertures like those assigned to Faces with parent Rooms.

remove_assigned_doors()

Remove all Doors assigned to the model’s Faces.

This includes nested doors like those assigned to Faces with parent Rooms.

remove_assigned_shades()

Remove all Shades assigned to the model’s Rooms, Faces, Apertures and Doors.

This includes nested shades like those assigned to Apertures with parent Faces that have parent Rooms.

remove_degenerate_geometry(tolerance=None)

Remove any degenerate geometry from the model.

Degenerate geometry refers to any objects that evaluate to less than 3 vertices when duplicate and colinear vertices are removed at the tolerance.

Parameters

tolerance – The minimum distance between a vertex and the boundary segments at which point the vertex is considered distinct. If None, the Model’s tolerance will be used. (Default: None).

remove_doors(door_ids=None)

Remove orphaned Doors from the model.

Parameters

door_ids – An optional list of Door identifiers to only remove certain doors from the model. If None, all Doors will be removed. (Default: None).

remove_faces(face_ids=None)

Remove orphaned Faces from the model.

Parameters

face_ids – An optional list of Face identifiers to only remove certain faces from the model. If None, all Faces will be removed. (Default: None).

remove_rooms(room_ids=None)

Remove Rooms from the model.

Parameters

room_ids – An optional list of Room identifiers to only remove certain rooms from the model. If None, all Rooms will be removed. (Default: None).

remove_shade_meshes(shade_mesh_ids=None)

Remove ShadeMeshes from the model.

Parameters

• shade_mesh_ids – An optional list of ShadeMesh identifiers to only remove

• None (certain shades from the model. If) –

• be (all Shades will) –

• (Default (removed.) – None).

remove_shades(shade_ids=None)

Remove orphaned Shades from the model.

Parameters

shade_ids – An optional list of Shade identifiers to only remove certain shades from the model. If None, all Shades will be removed. (Default: None).

reset_ids(repair_surface_bcs=True)

Reset the identifiers of all Model objects to be derived from display_names.

In the event that duplicate identifiers are found, an integer will be automatically appended to the new ID to make it unique. This is similar to the routines that automatically assign unique names to OpenStudio SDK objects.

Parameters

repair_surface_bcs – A Boolean to note whether all Surface boundary conditions across the model should be updated with the new identifiers that were generated from the display names. (Default: True).

reset_room_ids()

Reset the identifiers of the Model Rooms to be derived from display_names.

In the event that duplicate Room identifiers are found, an integer will be automatically appended to the new Room ID to make it unique.

Returns

A dictionary that relates the old identifiers (keys) to the new identifiers (values). This can be used to map between old and new objects and update things like Surface boundary conditions.

rooms_by_identifier(identifiers)

Get a list of Room objects in the model given the Room identifiers.

rooms_to_orphaned()

Convert all Rooms in this Model to orphaned geometry objects.

This is useful when the energy load balance of Rooms is not important and they are only significant as context shading. Note that this method will effectively discount any geometries with a Surface boundary condition or with an AirBoundary face type.

rotate(axis, angle, origin)

Rotate this Model by a certain angle around an axis and origin.

Parameters

• axis – A ladybug_geometry Vector3D axis representing the axis of rotation.

• angle – An angle for rotation in degrees.

• origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

rotate_xy(angle, origin)

Rotate this Model counterclockwise in the world XY plane by a certain angle.

Parameters

• angle – An angle in degrees.

• origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

scale(factor, origin=None)

Scale this Model by a factor from an origin point.

Note that using this method does NOT scale the model tolerance and, if it is desired that this tolerance be scaled with the model geometry, it must be scaled separately.

Parameters

• factor – A number representing how much the object should be scaled.

• origin – A ladybug_geometry Point3D representing the origin from which to scale. If None, it will be scaled from the World origin (0, 0, 0).

shade_meshes_by_identifier(identifiers)

Get a list of ShadeMesh objects in the model given the ShadeMesh identifiers.

shades_by_identifier(identifiers)

Get a list of Shade objects in the model given the Shade identifiers.

simplify_apertures(resolve_adjacency=True, tolerance=None)

Convert all Apertures in this Model to be a simple window ratio.

This is useful for studies where faster simulation times are desired and the window ratio is the critical factor driving the results (as opposed to the detailed geometry of the window). Apertures assigned to concave Faces will not be simplified given that the Face.apertures_by_ratio method likely won’t improve the cleanliness of the apertures for such cases.

Parameters

• resolve_adjacency – Boolean to note whether Room adjacencies should be re-solved after the Apertures have been simplified. Setting this to True should ensure that and interior Apertures that are simplified retain their Surface boundary conditions. If False, all interior Apertures that have been simplified will have an Outdoors boundary condition. (Default: True).

• tolerance – The maximum difference between point values for them to be considered equivalent. If None, the Model tolerance will be used. (Default: None).

skylight_apertures_by_ratio(ratio, tolerance=None)

Add apertures to all exterior roofs given a ratio of aperture to face area.

Note this method only affects the Models rooms (no orphaned faces) and removes any existing apertures and overhead doors on the Room’s roofs. This method attempts to generate as few apertures as necessary to meet the ratio.

Parameters

• ratio – A number between 0 and 1 (but not perfectly equal to 1) for the desired ratio between aperture area and face area.

• tolerance – The maximum difference between point values for them to be considered a part of a rectangle. This is used in the event that this face is concave and an attempt to subdivide the face into a rectangle is made. It does not affect the ability to produce apertures for convex Faces. If None, the Model tolerance will be used. (Default: None).

solve_adjacency(merge_coplanar=False, intersect=False, overwrite=False, air_boundary=False, adiabatic=False, tolerance=None, angle_tolerance=None)

Solve adjacency between Rooms of the Model.

Parameters

• merge_coplanar – Boolean to note whether coplanar Faces of the Rooms should be merged before proceeding with the rest of the adjacency solving. This is particularly helpful when used with the intersect option since it will ensure the Room geometry is relatively clean before the intersection and adjacency solving occurs. (Default: False).

• intersect – Boolean to note whether the Faces of the Rooms should be intersected with one another before the adjacencies are solved. (Default: False).

• overwrite – Boolean to note whether existing Surface boundary conditions should be overwritten. (Default: False).

• air_boundary – Boolean to note whether the wall adjacencies should be of the air boundary face type. (Default: False).

• adiabatic – Boolean to note whether the adjacencies should be surface or adiabatic. Note that this requires honeybee-energy to be installed in order to have any meaning. (Default: False).

• tolerance – The maximum difference between point values for them to be considered equivalent. If None, the Model tolerance will be used. (Default: None).

• angle_tolerance – The max angle difference in degrees where Face normals are no longer considered coplanar. If None, the Model angle_tolerance will be used. (Default: None).

to_dict(included_prop=None, triangulate_sub_faces=False, include_plane=True)

Return Model as a dictionary.

Parameters

• included_prop – List of properties to filter keys that must be included in output dictionary. For example [‘energy’] will include ‘energy’ key if available in properties to_dict. By default all the keys will be included. To exclude all the keys from extensions use an empty list.

• triangulate_sub_faces – Boolean to note whether sub-faces (including Apertures and Doors) should be triangulated if they have more than 4 sides (True) or whether they should be left as they are (False). This triangulation is necessary when exporting directly to EnergyPlus since it cannot accept sub-faces with more than 4 vertices. Note that setting this to True will only triangulate sub-faces with parent Faces that also have parent Rooms since orphaned Apertures and Faces are not relevant for energy simulation. (Default: False).

• include_plane – Boolean to note wether the planes of the Face3Ds should be included in the output. This can preserve the orientation of the X/Y axes of the planes but is not required and can be removed to keep the dictionary smaller. (Default: True).

to_hbjson(name=None, folder=None, indent=None, included_prop=None, triangulate_sub_faces=False)

Write Honeybee model to HBJSON.

Parameters

• name – A text string for the name of the HBJSON file. If None, the model identifier wil be used. (Default: None).

• folder – A text string for the directory where the HBJSON will be written. If unspecified, the default simulation folder will be used. This is usually at “C:UsersUSERNAMEsimulation.”

• indent – A positive integer to set the indentation used in the resulting HBJSON file. (Default: None).

• included_prop – List of properties to filter keys that must be included in output dictionary. For example [‘energy’] will include ‘energy’ key if available in properties to_dict. By default all the keys will be included. To exclude all the keys from extensions use an empty list.

• triangulate_sub_faces – Boolean to note whether sub-faces (including Apertures and Doors) should be triangulated if they have more than 4 sides (True) or whether they should be left as they are (False). This triangulation is necessary when exporting directly to EnergyPlus since it cannot accept sub-faces with more than 4 vertices. Note that setting this to True will only triangulate sub-faces with parent Faces that also have parent Rooms since orphaned Apertures and Faces are not relevant for energy simulation. (Default: False).

to_hbpkl(name=None, folder=None, included_prop=None, triangulate_sub_faces=False)

Write Honeybee model to compressed pickle file (HBpkl).

Parameters

• name – A text string for the name of the pickle file. If None, the model identifier wil be used. (Default: None).

• folder – A text string for the directory where the pickle file will be written. If unspecified, the default simulation folder will be used. This is usually at “C:UsersUSERNAMEsimulation.”

• included_prop – List of properties to filter keys that must be included in output dictionary. For example [‘energy’] will include ‘energy’ key if available in properties to_dict. By default all the keys will be included. To exclude all the keys from extensions use an empty list.

• triangulate_sub_faces – Boolean to note whether sub-faces (including Apertures and Doors) should be triangulated if they have more than 4 sides (True) or whether they should be left as they are (False). This triangulation is necessary when exporting directly to EnergyPlus since it cannot accept sub-faces with more than 4 vertices. Note that setting this to True will only triangulate sub-faces with parent Faces that also have parent Rooms since orphaned Apertures and Faces are not relevant for energy simulation. (Default: False).

to_stl(name=None, folder=None)

Write Honeybee model to an ASCII STL file.

Note that all geometry is triangulated when it is converted to STL.

Parameters

• name – A text string for the name of the STL file. If None, the model identifier wil be used. (Default: None).

• folder – A text string for the directory where the STL will be written. If unspecified, the default simulation folder will be used. This is usually at “C:UsersUSERNAMEsimulation.”

triangulate_non_planar_quads(tolerance=None)

Triangulate any non-planar orphaned geometry in the model.

This method will only planarize the orphaned Faces, Apertures, Doors and Shades that are quadrilaterals, which usually has a minimal impact on results. It does not impact the Rooms at all.

Parameters

tolerance – The minimum distance from the geometry plane at which the geometry is not considered planar. If None, the Model’s tolerance will be used. (Default: None).

triangulated_apertures()

Get triangulated versions of the model Apertures that have more than 4 sides.

This is necessary for energy simulation since EnergyPlus cannot accept sub-faces with more than 4 sides. Note that this method does not alter the Apertures within the Model object but just returns a list of modified Apertures that all have 3 or 4 sides.

Returns

A tuple with two elements

• triangulated_apertures: A list of lists where each list is a set of triangle Apertures meant to replace an Aperture with more than 4 sides in the model.

• parents_to_edit: An list of lists that parallels the triangulated apertures in that each item represents an Aperture that has been triangulated in the model. However, each of these lists holds between 1 and 3 values for the identifiers of the original aperture and parents of the aperture. This information is intended to help edit parent faces that have had their child faces triangulated. The 3 values are as follows:

  • 0 = The identifier of the original Aperture that was triangulated.

  • 1 = The identifier of the parent Face of the original Aperture (if it exists).

  • 2 = The identifier of the parent Room of the parent Face of the original Aperture (if it exists).

triangulated_doors()

Get triangulated versions of the model Doors that have more than 4 sides.

This is necessary for energy simulation since EnergyPlus cannot accept sub-faces with more than 4 sides. Note that this method does not alter the Doors within the Model object but just returns a list of Doors that all have 3 or 4 sides.

Returns

A tuple with two elements

• triangulated_doors: A list of lists where each list is a set of triangle Doors meant to replace a Door with more than 4 sides in the model.

• parents_to_edit: An list of lists that parallels the triangulated_doors in that each item represents a Door that has been triangulated in the model. However, each of these lists holds between 1 and 3 values for the identifiers of the original door and parents of the door. This information is intended to help edit parent faces that have had their child faces triangulated. The 3 values are as follows:

  • 0 = The identifier of the original Door that was triangulated.

  • 1 = The identifier of the parent Face of the original Door (if it exists).

  • 2 = The identifier of the parent Room of the parent Face of the original Door (if it exists).

wall_apertures_by_ratio(ratio, tolerance=None)

Add apertures to all exterior walls given a ratio of aperture to face area.

Note this method only affects the Models rooms (no orphaned faces) and it removes any existing apertures and doors on the room’s exterior walls. This method attempts to generate as few apertures as necessary to meet the ratio.

Parameters

• ratio – A number between 0 and 1 (but not perfectly equal to 1) for the desired ratio between aperture area and face area.

• tolerance – The maximum difference between point values for them to be considered a part of a rectangle. This is used in the event that this face is concave and an attempt to subdivide the face into a rectangle is made. It does not affect the ability to produce apertures for convex Faces. If None, the Model tolerance will be used. (Default: None).

UNITS = ('Meters', 'Millimeters', 'Feet', 'Inches', 'Centimeters')

UNITS_TOLERANCES = {'Centimeters': 1.0, 'Feet': 0.01, 'Inches': 0.1, 'Meters': 0.01, 'Millimeters': 1.0}

property angle_tolerance

Get or set a number for the max meaningful angle difference in degrees.

Face3D normal vectors differing by this amount are not considered parallel and Face3D segments that differ from 180 by this amount are not considered colinear. Zero indicates cases where no angle_tolerance checks should be performed.

property apertures

Get a list of all Aperture objects in the model.

property display_name

Get or set a string for the object name without any character restrictions.

If not set, this will be equal to the identifier.

property doors

Get a list of all Door objects in the model.

property exposed_area

Get the combined area of all room faces with outdoor boundary conditions.

Useful for estimating infiltration, often expressed as a flow per unit exposed envelope area. Note that this property accounts for the room multipliers.

property exterior_aperture_area

Get the combined area of all exterior apertures on the model’s rooms.

Note that this property accounts for the room multipliers.

property exterior_roof_area

Get the combined area of all exterior roofs on the model’s rooms.

This is NOT the area of the roof’s punched_geometry and it includes BOTH the area of opaque and transparent parts of the roofs. Note that this property accounts for the room multipliers.

property exterior_skylight_aperture_area

Get the combined area of all apertures on exterior roofs of the model’s rooms.

Note that this property accounts for the room multipliers.

property exterior_wall_aperture_area

Get the combined area of all apertures on exterior walls of the model’s rooms.

Note that this property accounts for the room multipliers.

property exterior_wall_area

Get the combined area of all exterior walls on the model’s rooms.

This is NOT the area of the wall’s punched_geometry and it includes BOTH the area of opaque and transparent parts of the walls. Note that this property accounts for the room multipliers.

property faces

Get a list of all Face objects in the model.

property floor_area

Get the combined area of all room floor faces in the Model.

Note that this property accounts for the room multipliers.

property full_id

Get a string with both the object display_name and identifier.

This is formatted as display_name[identifier].

This is useful in error messages to give users an easy means of finding invalid objects within models. If there is no display_name assigned, only the identifier will be returned.

property grouped_shades

Get a list of lists where each sub-list contains Shades and/or ShadeMeshes with the same display_name.

Assigning a common display_name to Shades and ShadeMeshes is the officially recommended way to group these objects for export to platforms that support shade groups. In this case, it is customary to use the common display_name as the name of the shade group.

Note that, if no display_names have been assigned to the Shades and ShadeMeshes, the unique object identifier is used, meaning each sublist returned here should have only one item in it.

property identifier

Get or set a text string for the unique object identifier.

This identifier remains constant as the object is mutated, copied, and serialized to different formats (eg. dict, idf, rad). As such, this property is used to reference the object across a Model.

property indoor_shades

Get a list of all indoor Shade objects in the model.

property max

Get a Point3D for the max bounding box vertex in the XY plane.

property min

Get a Point3D for the min bounding box vertex in the XY plane.

property orphaned_apertures

Get a tuple of all Aperture objects without parent Faces in the model.

property orphaned_doors

Get a tuple of all Door objects without parent Faces in the model.

property orphaned_faces

Get a tuple of all Face objects without parent Rooms in the model.

property orphaned_shades

Get a tuple of all Shade objects without parent Rooms in the model.

property outdoor_shades

Get a list of all outdoor Shade objects in the model.

This includes all of the orphaned_shades.

property properties

Get object properties, including Radiance, Energy and other properties.

property rooms

Get a tuple of all Room objects in the model.

property shade_meshes

Get a tuple of all ShadeMesh objects in the model.

property shades

Get a list of all Shade objects in the model.

property stories

Get a list of text for each unique story identifier in the Model.

Note that this will be an empty list if the model has to rooms.

property to

Model writer object.

Use this method to access Writer class to write the model in other formats.

Usage:

model.to.idf(model) -> idf string.
model.to.radiance(model) -> Radiance string.

property tolerance

Get or set a number for the max meaningful difference between x, y, z values.

This value should be in the Model’s units. Zero indicates cases where no tolerance checks should be performed.

property top_level_dict

Get dictionary of top-level model objects with identifiers as the keys.

This is useful for matching these objects to others using identifiers.

property units

Get or set Text for the units system in which the model geometry exists.

property user_data

Get or set an optional dictionary for additional meta data for this object.

This will be None until it has been set. All keys and values of this dictionary should be of a standard Python type to ensure correct serialization of the object to/from JSON (eg. str, float, int, list, dict)

property volume

Get the combined volume of all rooms in the Model.

Note that this property accounts for the room multipliers. Also note that, if this model’s rooms are not closed solids, the value of this property will not be accurate.