dragonfly.story module

Dragonfly Story.

class dragonfly.story.Story(identifier, room_2ds, floor_to_floor_height=None, floor_height=None, multiplier=1, roof=None)

Bases: _BaseGeometry

A Story of a building defined by an extruded Room2Ds.

Parameters:

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

• room_2ds – An array of dragonfly Room2D objects that together form an entire story of a building.

• floor_to_floor_height – A number for the distance from the floor plate of this Story to the floor of the story above this one (if it exists). This should be in the same units system as the input room_2d geometry. If None, this value will be the maximum floor_to_ceiling_height of the input room_2ds plus any difference between the Story floor height and the room floor heights. (Default: None)

• floor_height – A number for the absolute floor height of the Story. If None, this will be the minimum floor height of all the Story’s room_2ds, which is suitable for cases where there are no floor plenums. (Default: None).

• multiplier – An integer that denotes the number of times that this Story is repeated over the height of the building. (Default: 1).

• roof – An optional RoofSpecification object containing geometry and instructions for generating sloped roofs over a Story. The RoofSpecification will only affect the child Room2Ds that have a True is_top_exposed property and it will only be utilized in translation to Honeybee when the Story multiplier is 1. If None, all Room2D ceilings will be flat. (Default: None).

Properties:

• identifier

• display_name

• full_id

• room_2ds

• floor_to_floor_height

• multiplier

• roof

• parent

• has_parent

• floor_height

• floor_area

• exterior_wall_area

• exterior_aperture_area

• volume

• is_above_ground

• min

• max

• median_room2d_floor_height

• user_data

ToString()

Overwrite .NET ToString.

add_prefix(prefix)

Change the identifier and all child Room2D ids by inserting a prefix.

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

This method is used internally to convert from a Story with a multiplier to fully-detailed Stories with unique identifiers.

Parameters:

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

add_room_2d(room_2d)

Add a Room2D to this Story.

No check will be performed for whether the input room_2d’s identifier matches one in the current Story.

Parameters:

room_2d – A Room2D object to be added to this Story.

add_room_2ds(rooms_2ds, add_duplicate_ids=False)

Add a list of Room2Ds to this Story with checks for duplicate identifiers.

Parameters:

• room_2d – A list of Room2D objects to be added to this Story.

• add_duplicate_ids – A boolean to note whether added Room2Ds that have matching identifiers within the current Story should be ignored (False) or they should be added to the Story creating an ID collision that can be resolved later (True). (Default: False).

align(line_ray, distance, tolerance=0.01)

Move Room2D and Roof vertices within a distance of a line to be on that line.

This method differs from the align_room_2ds method in that it will also align any Roof geometry (if it is present).

Parameters:

• line_ray – A ladybug_geometry Ray2D or LineSegment2D to which the Room2D and Roof vertices will be aligned. Ray2Ds will be interpreted as being infinite in both directions while LineSegment2Ds will be interpreted as only existing between two points.

• distance – The maximum distance between a vertex and the line_ray where the vertex will be moved to lie on the line_ray. Vertices beyond this distance will be left as they are.

• tolerance – The minimum distance between vertices below which they are considered co-located. This is used to ensure that the alignment process does not create new overlaps in the roof geometry. (Default: 0.01, suitable for objects in meters).

align_room_2ds(line_ray, distance)

Move Room2D vertices within a given distance of a line to be on that line.

Note that, when there are small Room2Ds next to the input line_ray, this method can create degenerate Room2Ds and so it may be wise to run the delete_degenerate_room_2ds method after running this one.

Parameters:

• line_ray – A ladybug_geometry Ray2D or LineSegment2D to which the Room2D vertices will be aligned. Ray2Ds will be interpreted as being infinite in both directions while LineSegment2Ds will be interpreted as only existing between two points.

• distance – The maximum distance between a vertex and the line_ray where the vertex will be moved to lie on the line_ray. Vertices beyond this distance will be left as they are.

check_missing_adjacencies(raise_exception=True, detailed=False)

Check that all Room2Ds have adjacent objects that exist within this Story.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if missing or 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_no_roof_overlaps(tolerance=0.01, raise_exception=True, detailed=False)

Check that geometries of RoofSpecifications do not overlap with one another.

This is NOT required for the Story to be valid but it is sometimes useful to check since it can indicate whether the roof can be cleaned up into a clearer and more concise set of geometries.

Parameters:

• tolerance – The minimum distance that two Roof geometries can overlap with one another and still be considered valid. Default: 0.01, suitable for objects in meters.

• raise_exception – Boolean to note whether a ValueError should be raised if overlapping geometries 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_no_room2d_overlaps(tolerance=0.01, raise_exception=True, detailed=False)

Check that geometries of Room2Ds do not overlap with one another.

Overlaps in Room2Ds mean that the Room volumes will collide with one another during translation to Honeybee.

Parameters:

• tolerance – The minimum distance that two Room2Ds geometries can overlap with one another and still be considered valid. (Default: 0.01, suitable for objects in meters).

• raise_exception – Boolean to note whether a ValueError should be raised if overlapping geometries 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_roofs_above_rooms(tolerance=0.01, raise_exception=True, detailed=False)

Check that geometries of RoofSpecifications all lie above the Room2D geometry.

Roofs that lie below the Room2Ds will result in invalid Honeybee Rooms with self-intersecting walls.

Parameters:

• tolerance – The minimum distance between coordinate values that is considered a meaningful difference. (Default: 0.01, suitable for objects in meters).

• raise_exception – Boolean to note whether a ValueError should be raised if roof geometries are found below the Room2D geometries. (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_room2d_floor_heights_valid(raise_exception=True, detailed=False)

Check that all Room2Ds have floor elevations in range to be on the same Story.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if rooms with inappropriate floor elevations 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.

delete_degenerate_room_2ds(tolerance=0.01)

Remove all Room2Ds with a floor_area of zero from this Story.

This method will also automatically remove any degenerate holes in Room2D floor geometries, which have an area less than zero.

Parameters:

tolerance – The minimum difference between the coordinate values at which they are considered co-located. Default: 0.01, suitable for objects in meters.

Returns:

A list of all degenerate Room2Ds that were removed.

duplicate()

Get a copy of this object.

floor_geometry(tolerance=0.01)

Get a ladybug_geometry Polyface3D object representing the floor plate.

Parameters:

tolerance – The minimum distance between points at which they are not considered touching. Default: 0.01, suitable for objects in meters.

footprint(tolerance=0.01)

Get a list of Face3D objects for the minimum floor plate representation.

Parameters:

tolerance – The minimum distance between points at which they are not considered touching. (Default: 0.01, suitable for objects in meters).

classmethod from_dict(data, tolerance=0)

Initialize a Story from a dictionary.

Parameters:

• data – A dictionary representation of a Story object.

• tolerance – The maximum difference between z values at which point vertices are considered to be in the same horizontal plane. This is used to check that all vertices of the input floor_geometry lie in the same horizontal floor plane. Default is 0, which will not perform any check.

classmethod from_honeybee(identifier, rooms, tolerance)

Initialize a Story from a list of Honeybee Rooms.

Parameters:

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

• rooms – A list of Honeybee Room objects.

• tolerance – The maximum difference between values at which point vertices are considered to be the same.

generate_grid(x_dim, y_dim=None, offset=1.0)

Get a list of gridded Mesh3D objects offset from the floors of this story.

Parameters:

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

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

• offset – A number for how far to offset the grid from the base face. Default is 1.0, which will not offset the grid to be 1 unit above the floor.

intersect_room_2d_adjacency(tolerance=0.01)

Automatically intersect the line segments of the Story’s Room2Ds.

Note that this method effectively erases window parameters and shading parameters for any intersected segments as the original segments are subdivided. As such, it is recommended that this method be used before assigning window or shading parameters.

Parameters:

tolerance – The minimum difference between the coordinate values of two at which they can be considered adjacent. (Default: 0.01, suitable for objects in meters).

join_small_rooms(area_threshold, tolerance=0.01)

Join small Room2Ds together within this Story.

This is particularly useful when operations like automatic core/perimeter zoning creates several small Room2Ds from small segments in the outline boundary around the Story.

Note that adjacencies should be solved across the Story for this method to function correctly.

Parameters:

• area_threshold – A number for the Room2D floor area below which it is considered a small room to be joined into adjacent rooms.

• tolerance – The minimum distance between vertices at which point they are considered equivalent. (Default: 0.01, suitable for objects in meters).

make_underground()

Make this Story underground by setting all Room2D segments to have Ground BCs.

Note that this method only changes the outdoor walls of the Room2Ds to have Ground boundary conditions and, if the floors of the story are also in contact with the ground, the set_ground_contact should be used in addition to this method.

Also note that this method will throw an exception if any of the Room2Ds have WindowParameters assigned to them (since Ground boundary conditions are) not compatible with windows. So using the set_outdoor_window_parameters method and passing None to remove all windows is often recommended before running this method.

move(moving_vec)

Move this Story along a vector.

Parameters:

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

outline_polylines(tolerance=0.01)

Get a list of Polyline3D objects for the outline of the floor plate.

Note that these segments include both the boundary surrounding the floor and any holes for courtyards that exist within the floor.

Parameters:

tolerance – The minimum distance between points at which they are not considered touching. Default: 0.01, suitable for objects in meters.

outline_segments(tolerance=0.01)

Get a list of LineSegment3D objects for the outline of the floor plate.

Note that these segments include both the boundary surrounding the floor and any holes for courtyards that exist within the floor.

Parameters:

tolerance – The minimum distance between points at which they are not considered touching. Default: 0.01, suitable for objects in meters.

rebuild_detailed_windows(tolerance=0.01, match_adjacency=False, rebuild_skylights=True)

Rebuild all detailed windows such that they are bounded by their parent walls.

This method will also ensure that all interior windows on adjacent wall segments are matched correctly with one another.

This is useful to run after situations where Room2D vertices have been moved, which can otherwise disrupt the pattern of detailed windows.

Parameters:

• tolerance – The minimum distance between a vertex and the edge of the wall segment that is considered not touching. (Default: 0.01, suitable for objects in meters).

• match_adjacency – A boolean to note whether this method should ensure that all interior windows on adjacent wall segments are matched correctly with one another. This is desirable when the existing adjacencies across the model are correct but it can create several unwanted cases when the adjacencies are not correct. (Default: False).

• rebuild_skylights – A boolean to note whether skylights should be offset and rebuilt if they lie outside their parent Room2D.

reflect(plane)

Reflect this Story across a plane.

Parameters:

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

remove_room_2d_colinear_vertices(tolerance=0.01, preserve_wall_props=True, delete_degenerate=False)

Automatically remove colinear or duplicate vertices for the Story’s Room2Ds.

Parameters:

• tolerance – The minimum difference between the coordinate values at which they are considered co-located. Default: 0.01, suitable for objects in meters.

• preserve_wall_props – Boolean to note whether existing window parameters and Ground boundary conditions should be preserved as vertices are removed. If False, all boundary conditions are replaced with Outdoors, all window parameters are erased, and this method will execute quickly. If True, an attempt will be made to merge window parameters together across colinear segments, translating simple window parameters to rectangular ones if necessary. Also, existing Ground boundary conditions will be kept. (Default: True).

• delete_degenerate – Boolean to note whether degenerate Room2Ds (with floor geometries that evaluate to less than 3 vertices at the tolerance) should be deleted from the Story instead of raising a ValueError. (Default: False).

Returns:

A list of all degenerate Room2Ds that were removed if delete_degenerate is True. Will be None if delete_degenerate is False.

remove_room_2d_duplicate_vertices(tolerance=0.01, delete_degenerate=False)

Remove duplicate vertices from all Room2Ds in this Story.

All properties assigned to the Room2D will be preserved and any changed Surface boundary conditions will be automatically updated based on the removed wall segment indices.

Parameters:

• tolerance – The minimum distance between a vertex and the line it lies upon at which point the vertex is considered duplicated. Default: 0.01, suitable for objects in meters).

• delete_degenerate – Boolean to note whether degenerate Room2Ds (with floor geometries that evaluate to less than 3 vertices at the tolerance) should be deleted from the Story instead of raising a ValueError. Note that using this option frequently creates invalid missing adjacencies, requiring the run of reset_adjacencies followed by re-running solve_adjacency. (Default: False).

Returns:

A list of all degenerate Room2Ds that were removed if delete_degenerate is True. Will be None if delete_degenerate is False.

remove_room_2d_short_segments(distance, angle_tolerance=1.0)

Remove consecutive short segments on this Story’s Room2Ds.

To patch over the removed segments, an attempt will first be made to find the intersection of the two neighboring segments. If these two lines are parallel, they will simply be connected with a segment.

Properties assigned to the Room2Ds will be preserved for the segments that are not removed. Room2Ds that have all of their walls shorter than the distance will be removed from the Story.

Parameters:

• distance – The maximum length of a segment below which the segment will be considered for removal.

• angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. (Default: 1).

Returns:

A list of all small Room2Ds that were removed.

reset_adjacency()

Set all Surface boundary conditions on the Story to be Outdoors.

reset_room_2d_boundaries(polygons, identifiers=None, display_names=None, floor_to_ceiling_heights=None, tolerance=0.01)

Rebuild the Room2Ds of the Story using boundary Polygons.

All existing properties of segments along the boundary polygons will be preserved, including all window geometries. By default, the largest room that is identified within each of the boundary polygons will determine the extension properties of the resulting Room2D.

It is recommended that the Room2Ds be aligned to the boundaries of the polygon and duplicate vertices be removed before using this method.

Parameters:

• polygons – A list of ladybug_geometry Polygon2D, which will become the new boundaries of the Story’s Room2Ds. Note that it is acceptable to include hole polygons in this list and they will automatically be sensed by their relationship to the other polygons.

• identifiers – An optional list of text that align with the polygons and will dictate the identifiers of the Story’s Rooms. If this matches an existing Room2D inside of the polygon, the existing Room2D will be used to set the extension properties of the output Room2D. If None, the identifier and extension properties of the output Room2D will be those of the largest Room2D found inside of the polygon. (Default: None).

• display_names – An optional list of text that align with the polygons and will dictate the display_names of the Story’s Rooms. If None, the display_name will be taken from the largest existing Room2D inside the polygon or the existing Room2D matching the identifier above. (Default: None).

• floor_to_ceiling_heights – An optional list of numbers that align with the polygons and will dictate the the floor-to-ceiling heights of the resulting Room2Ds. If None, it will be the maximum of the Room2Ds that are found inside each of the polygon, which ensures that all window geometries are included in the output. If specified and it is lower than the maximum Room2D height, any detailed windows will be automatically trimmed to accommodate the new floor-to-ceiling height. (Default: None).

• tolerance – The minimum distance between a vertex and the polygon boundary at which point the vertex is considered to lie on the polygon. (Default: 0.01, suitable for objects in meters).

static room_2d_story_geometry_valid(room_2ds)

Check that a set of Room2Ds have geometry that makes a valid Story.

This means that all of the floors of the Room2Ds are close enough to one another in elevation that their walls could touch each other.

Parameters:

room_2ds – An array of Room2Ds that will be checked to ensure their geometry makes a valid Story.

Returns:

True if the Room2D geometries make a valid Story. False if they do not.

room_by_identifier(room_identifier)

Get a Room2D from this Story using its identifier.

Result will be None if the Room2D is not found in the Story.

Parameters:

room_identifier – String for the identifier of the Room2D to be retrieved from this story.

rooms_by_identifier(room_identifiers)

Get a list of Room2D objects in this story given Room2D identifiers.

Parameters:

room_identifier – Array of strings for the identifiers of the Room2D to be retrieved from this Story.

rotate_xy(angle, origin)

Rotate this Story counterclockwise in the 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 Story by a factor from an origin point.

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

set_adjacent_air_boundary(room_ids=None, guide_lines=None, tolerance=0.01)

Set adjacencies between Room2Ds in this Story to use air boundaries.

Parameters:

• room_ids – An optional list of Room2D identifiers to specify a subset of rooms within the Story that will have air boundaries set between them. If None, all Room2Ds in the story will have air boundaries set if they are adjacent to another. (Default: None).

• guide_lines – An optional list of LineSegment2Ds to specify a subset of rooms within the Story that will have air boundaries set between them. If None, all Room2Ds in the story will have air boundaries set if they are adjacent to another. (Default: None).

• tolerance – The minimum difference between the coordinate values of two faces at which they can be considered adjacent. (Default: 0.01, suitable for objects in meters).

set_ground_contact(is_ground_contact=True)

Set all child Room2Ds of this object to have floors with ground contact.

Parameters:

is_ground_contact – A boolean noting whether all the Story’s room_2ds have floors in contact with the ground. Default: True.

set_outdoor_shading_parameters(shading_parameter)

Set all of the outdoor walls to have the same shading parameters.

Parameters:

shading_parameter – A ShadingParameter object that will be assigned to all wall segments of this story’s rooms that have an Outdoors boundary conditions. This can also be None, to remove all shades from the story.

set_outdoor_window_parameters(window_parameter)

Set all of the outdoor walls to have the same window parameters.

Parameters:

window_parameter – A WindowParameter object that will be assigned to all wall segments of this story’s rooms that have an Outdoors boundary conditions. This can also be None, to remove all windows from the story.

set_top_exposed(is_top_exposed=True)

Set all child Room2Ds of this object to have ceilings exposed to the outdoors.

Parameters:

is_top_exposed – A boolean noting whether all the Story’s room_2ds have ceilings exposed to the outdoors. Default: True.

set_top_exposed_by_story_above(story_above, tolerance=0.01)

Set the child Room2Ds of this object to have ceilings exposed to the outdoors.

Parameters:

• story_above – A Story object that sits above this Story. Each Room2D of this Story will be checked to see if the story_above geometry lies above the room and, if not, the top exposure will be set to True.

• tolerance – The tolerance that will be used to compute the point within the floor boundary that is used to check whether there is geometry above each Room2D. It is recommended that this number not be less than 1 centimeter to avoid long computation times. Default: 0.01, suitable for objects in meters.

shade_representation(cap=False, tolerance=0.01)

A list of honeybee Shade objects representing the story geometry.

This accounts for the story multiplier and can be used to account for this Story’s shade in the simulation of another nearby Story.

Parameters:

• cap – Boolean to note whether the shade representation should be capped with a top face. Usually, this is not necessary to account for blocked sun and is only needed when it’s important to account for reflected sun off of roofs. (Default: False).

• tolerance – The minimum distance between points at which they are not considered touching. Default: 0.01, suitable for objects in meters.

shade_representation_multiplier(exclude_index=0, cap=False, tolerance=0.01)

A list of honeybee Shade objects for just the “multiplier” part of the story.

This includes all of the geometry along the height of the multiplier except for one of the floors (represented by the exclude_index). This will be an empty list if the story has a multiplier of 1.

Parameters:

• exclude_index – An optional index for a story along the multiplier to be excluded from the shade representation. For example, if 0, the bottom geometry along the multiplier is excluded. (Default: 0).

• cap – Boolean to note whether the shade representation should be capped with a top face. Usually, this is not necessary to account for blocked sun and is only needed when it’s important to account for reflected sun off of roofs. (Default: False).

• tolerance – The minimum distance between points at which they are not considered touching. Default: 0.01, suitable for objects in meters.

solve_room_2d_adjacency(tolerance=0.01, intersect=False, resolve_window_conflicts=True)

Automatically solve adjacencies across the Room2Ds in this Story.

Parameters:

• tolerance – The minimum difference between the coordinate values of two faces at which they can be considered adjacent. (Default: 0.01, suitable for objects in meters).

• intersect – Boolean to note wether the Room2Ds should be intersected to obtain matching wall segments before solving adjacency. Note that setting this to True will result in the loss of windows and shades assigned to intersected segments. (Default: False).

• resolve_window_conflicts – Boolean to note whether conflicts between window parameters of adjacent segments should be resolved during adjacency setting or an error should be raised about the mismatch. Resolving conflicts will default to the window parameters with the larger are and assign them to the other segment. (Default: True).

split_with_story_above(story_above, tolerance=0.01)

Split the child Room2Ds of this object with the footprint of the Story above.

This is useful as a pre-step before running set_top_exposed_by_story_above as it ensures all top-exposed areas of this Story have a Room2D that can be set to exposed.

Parameters:

• story_above – A Story object that sits above this Story. Each Room2D of this Story will be checked to see if it intersects the Story above and it will be split based on this.

• tolerance – The tolerance with which the splitting intersection will be computed. Default: 0.01, suitable for objects in meters.

suggested_alignment_axes(distance, direction=Vector2D(0.00, 1.00), angle_tolerance=1.0)

Get suggested LineSegment2Ds to be used for this Story in the align methods.

This method will return the most common axes across the Story geometry along with the number of Room2D segments that correspond to each axis. The latter can be used to filter the suggested alignment axes to get only the most common ones across the input Room2Ds.

Parameters:

• distance – A number for the distance that will be used in the alignment operation. This will be used to determine the resolution at which alignment axes are generated and evaluated. Smaller alignment distances will result in the generation of more common_axes since a finer resolution can differentiate common that would typically be grouped together. For typical building geometry, an alignment distance of 0.3 meters or 1 foot is typically suitable for eliminating unwanted details while not changing the geometry too much from its original location.

• direction – A Vector2D object to represent the direction in which the common axes will be evaluated and generated.

• angle_tolerance – The max angle difference in radians that the Room2D segment direction can differ from the input direction before the segments are not factored into this calculation of common axes.

• Returns – A tuple with two elements.

• common_axes (-) – A list of LineSegment2D objects for the common axes across the input Room2Ds.

• axis_values (-) – A list of integers that aligns with the common_axes and denotes how many segments of the input Room2D each axis relates to. Higher numbers indicate that that the axis is more commonly aligned across the Room2Ds.

to_dict(abridged=False, included_prop=None)

Return Story as a dictionary.

Parameters:

• abridged – Boolean to note whether the extension properties of the object (ie. construction sets) should be included in detail (False) or just referenced by identifier (True). Default: False.

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

to_honeybee(use_multiplier=True, add_plenum=False, tolerance=0.01, enforce_adj=True, enforce_solid=True)

Convert Dragonfly Story to a list of Honeybee Rooms.

Parameters:

• use_multiplier – If True, this Story’s multiplier will be passed along to the generated Honeybee Room objects, indicating the simulation will be run once for the Story and then results will be multiplied. You will want to set this to False when exporting each Story as full geometry.

• add_plenum – Boolean to indicate whether ceiling/floor plenums should be auto-generated for the Rooms. (Default: False).

• tolerance – The minimum distance in z values of floor_height and floor_to_ceiling_height at which adjacent Faces will be split. If None, no splitting will occur. (Default: 0.01, suitable for objects in meters).

• enforce_adj – Boolean to note whether an exception should be raised if an adjacency between two Room2Ds is invalid (True) or if the invalid Surface boundary condition should be replaced with an Outdoor boundary condition (False). If False, any Walls containing WindowParameters and an illegal boundary condition will also be replaced with an Outdoor boundary condition. (Default: True).

• enforce_solid – Boolean to note whether rooms should be translated as solid extrusions whenever translating them with custom roof geometry produces a non-solid result (True) or the non-solid room geometry should be allowed to remain in the result (False). The latter is useful for understanding why a particular roof geometry has produced a non-solid result. (Default: True).

Returns:

A list of honeybee Rooms that represent the Story.

to_rectangular_windows()

Convert all of the windows of the Story to the RectangularWindows format.

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 exterior_aperture_area

Get a number for the total exterior aperture area in the Story.

Note that this property is for one story and does NOT use the multiplier. However, if this Story is assigned to a parent Building with room_3ds, it will include the exterior wall aperture area of these 3D Rooms (without the room multiplier).

property exterior_wall_area

Get a number for the total exterior wall area in the Story.

Note that this property is for one story and does NOT use the multiplier. However, if this Story is assigned to a parent Building with room_3ds, it will include the wall area of these 3D Rooms (without the room multiplier).

property floor_area

Get a number for the total floor area in the Story.

Note that this property is for one Story and does NOT use the multiplier. However, if this Story is assigned to a parent Building with room_3ds, it will include the floor area of these 3D Rooms (without the room multiplier).

property floor_height

Get or set a number for the absolute floor height of the Story.

This will be the minimum floor height of all the Story’s room_2ds unless specified otherwise.

property floor_to_floor_height

Get or set a number for the distance from this floor plate to the next one.

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 has_parent

Boolean noting whether this Story has a parent Building.

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). This property is also used to reference the object across a Model.

property is_above_ground

Get a boolean to note if this Story is above the ground.

The story is considered above the ground if at least one of its Room2Ds has an outdoor boundary condition for its walls.

property max

Get a Point2D for the max bounding rectangle vertex in the XY plane.

This is useful in calculations to determine if this Story is in proximity to others.

property median_room2d_floor_height

Get the median floor height of the Room2Ds of this Story.

property min

Get a Point2D for the min bounding rectangle vertex in the XY plane.

This is useful in calculations to determine if this Story is in proximity to others.

property multiplier

Get or set an integer noting how many times this Story is repeated.

Multipliers are used to speed up the calculation when similar Stories are repeated more than once. Essentially, a given simulation with the Story is run once and then the result is multiplied by the multiplier. This comes with some inaccuracy. However, this error might not be too large if the Stories are similar enough and it can often be worth it since it can greatly speed up the calculation.

For more information on multipliers in EnergyPlus see EnergyPlus Tips and Tricks: https://bigladdersoftware.com/epx/docs/9-1/tips-and-tricks-using-energyplus/using-multipliers-zone-and-or-window.html

property parent

Parent Building if assigned. None if not assigned.

property properties

Object properties, including Radiance, Energy and other properties.

property roof

Get or set a RoofSpecification with instructions for generating sloped roofs.

The RoofSpecification will only affect the child Room2Ds that have a True is_top_exposed property and it will only be utilized in translation to Honeybee when the Story multiplier is 1.

property room_2ds

Get or set a tuple of Room2D objects that form the Story.

property to

Story writer object.

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

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 a number for the volume of all the Rooms in the Story.

Note that this property is for one story and does NOT use the multiplier. However, if this Story is assigned to a parent Building with room_3ds, it will include the volume of these 3D Rooms (without the room multiplier).