- [source code]

Deconstruct any Dragonfly geometry object into ALL of its constituent Dragonfly objects.

This is useful for editing auto-generated child objects separately from their parent. For example, if you want to assign all of the ground floors of a given auto-generated Building to have a Retail ProgramType, this can give you all of such Stories. Then you can assign a Retail ProgramType to them and combine them with the other Stories into a new Building.

Inputs

• df_obj [Required]

  A Dragonfly Building, Story or Room2D to be deconstructed into all of its constituent objects. Note that, Room2Ds do not have sub-objects assigned to them and the original object will be output.

Outputs

• all_stories

  Script variable Python

• all_room2ds

  Script variable Python

- [source code]

Create a Dragonfly Model, which can be translated to Honeybee model and sent for simulation.

Inputs

• buildings [Required]

  A list of Dragonfly Building objects to be added to the Model. Note that at least one Building is necessary to make a simulate-able energy model.

• context

  Optional Dragonfly ContextShade objects to be added to the Model.

• name

  Text to be used for the name and identifier of the Model. If no name is provided, it will be "unnamed".

Outputs

• report

  Reports, errors, warnings, etc.

• model

  A Dragonfly Model object possessing all of the input geometry objects.

• Deconstruct All Object

• Deconstruct Model

• Deconstruct Object

• Model

• Building from Detailed Rooms

• Building from Footprint

• Building from Solid

• Building from Stories

• Process Alleys

• Separate Top Bottom

• Rejoin to Building

• Story

• Room2D

• Solve Adjacency

• Apply Facade Parameters

• Detailed Windows

• Repeating Window Ratio Parameters

• Repeating Window Width Height Parameters

• Simple Window Ratio Parameters

• Single Window Parameters

• Extruded Border Parameters

• Gridded Skylight Parameters

• Louver Parameters

• Overhang Parameters

• Apply Roof

• Con..Shade

• Align

• BC by Orientation

• Deconstruct Roof

• Intersect Room2Ds

• Set Ground Top

This primer provides an overview of the Dragonfly components for Grasshopper.

The Dragonfly plugin supports the creation of models following the dragonfly-schema, which is an abstracted means of describing building geometry built on top of the honeybee-grasshopper plugin. By using a fundamentally 2D representation of Building geometry, where all rooms are assumed to be extrusions of floor plates, Dragonfly makes it easier to build models of large buildings all of the way up to the scale of urban districts. All Dragonfly models are translatable to Honeybee models and so all Dragonfly models can be simulated in the same engines as Honeybee, including EnergyPlus/OpenStudio and Radiance.

However, Dragonfly makes it easier to create these simulation models from common 2D formats like GeoJSON. It also enables the connection to a wider array of simulation engines including:

• URBANopt core SDK for modeling of district thermal systems

• DiTTo / OpenDSS for sizing transformers and electrical infrastructure

• REopt Lite for life cycle cost optimization of photovoltaics

• Urban Weather Generator for estimation of urban heat island effects

Installation

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

Resources

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

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

- [source code]

Deconstruct a Dragonfly Model object into all of its constituent Dragonfly objects.

Inputs

• model [Required]

  A Dragonfly Model to be deconstructed into into its constituent objects (Buildings, ContextShades).

Outputs

• buildings

  All of the Building objects contained within the input Model.

• context

  All of the ContextShade objects within the input Model.

- [source code]

Create a Dragonfly Building from individual Dragonfly Story objects.

Inputs

• stories [Required]

  A list of Dragonfly Story objects to be joined into one Building.

• multipliers

  An optional list of integers with the same length as the input _stories, which will be used to override any existing multipliers on the input Story objects. This integer denotes the number of times that each Story is repeated over the height of the building. If nothing is input here, the multipliers on the existing Story objects will remain.

• name

  Text to set the name for the Building, which will also be incorporated into unique Building identifier. If the name is not provided a random one will be assigned.

• constr_set

  Text for the construction set of the Building, which is used to assign all default energy constructions needed to create an energy model. Text should refer to a ConstructionSet within the library such as that output from the "HB List Construction Sets" component. This can also be a custom ConstructionSet object. If nothing is input here, the Building will have a generic construction set that is not sensitive to the Buildings's climate or building energy code.

Outputs

• report

  Reports, errors, warnings, etc.

• building

  Dragonfly Building.

- [source code]

Rejoin a list of Room2Ds that were originally a part of a Building back to a new Building with updated Room2Ds.

In the event that the input contains Room2Ds that were not a part of an original Building, this component can still be used but the stories will be regenerated based on the Room2D floor elevations and a warning will be given.

Inputs

• room2ds [Required]

A list of Dragonfly Room2D objects to be re-joined into Buildings.

Outputs

• buildings

Dragonfly Buildings containing the input Room2Ds. This may be multiple buildings when the input Room2Ds originally had several different parent buildings.

- [source code]

Create a Dragonfly Building from detailed Honeybee Rooms.

This is useful when there are parts of the Building geometry that cannot easily be represented with the extruded floor plate and sloped roof assumptions that underlie Dragonfly Room2Ds and RoofSpecification. Cases where this input is most useful include sloped walls and certain types of domed roofs that become tedious to implement with RoofSpecification.

Inputs

• base_bldg

An optional Dragonfly Building.

• hb_rooms [Required]

Honeybee Room objects for additional Rooms that are a part of the Building but are not represented within the Stories or Room2Ds. Matching the Honeybee Room story property (assigned with the "HB Set Multiplier" component) to the Dragonfly Story name will effectively place the Honeybee Room on that Story for the purposes of floor_area, exterior_wall_area, etc. However, note that the Honeybee Room.multiplier property takes precedence over whatever multiplier is assigned to the Dragonfly Story that the Room.story may reference.

• name

Text to set the name for the Building, which will also be incorporated into unique Building identifier. If the name is not provided a random one will be assigned.

Outputs

• report

Reports, errors, warnings, etc.

• building

Dragonfly Building.

- [source code]

Deconstruct any Dragonfly geometry object into its unique constituent Dragonfly objects.

This is useful for editing auto-generated child objects separately from their parent. For example, if you want to assign all of the ground floors of a given auto-generated Building to have a Retail ProgramType, this can give you all of such Stories. Then you can assign a Retail ProgramType to them and combine them with the other Stories into a new Building.

Inputs

• df_obj [Required]

  A Dragonfly Building, Story or Room2D to be deconstructed into its constituent objects. Note that, Room2Ds do not have sub-objects assigned to them and the original object will be output.

Outputs

• stories

  The unique Story objects that make up the input _df_obj. This includes unique Stories that make up input Buildings as well as any input orphaned Stories.

• room2ds

  The unique Room2D objects that make up the input _df_obj. This includes any unique Room2Ds assigned to input Stories or Buildings as well as any input orphaned Room2Ds.

- [source code]

Create Dragonfly Room2Ds from floor plate geometry (horizontal Rhino surfaces).

Inputs

• geo [Required]

A list of horizontal Rhino surfaces or closed planar polylines representing floor plates to be converted into Room2Ds.

• flr_to_ceiling [Required]

A number for the height above the floor where the ceiling begins. Typical values range from 3 to 5 meters.

• name

Text to set the base name for the Room2D, which will also be incorporated into unique Room2D identifier. This will be combined with the index of each input _footprint_geo to yield a unique name for each output Room2D. If the name is not provided, a random one will be assigned.

• program

Text for the program of the Room2Ds (to be looked up in the ProgramType library) such as that output from the "HB List Programs" component. This can also be a custom ProgramType object. If no program is input here, the Room2Ds will have a generic office program.

• constr_set

Text for the construction set of the Room2Ds, which is used to assign all default energy constructions needed to create an energy model. Text should refer to a ConstructionSet within the library such as that output from the "HB List Construction Sets" component. This can also be a custom ConstructionSet object. If nothing is input here, the Room2Ds will have a generic construction set that is not sensitive to the Room2Ds's climate or building energy code.

• conditioned

Boolean to note whether the Room2Ds have heating and cooling systems.

Outputs

• report

Reports, errors, warnings, etc.

• room2d

Dragonfly Room2Ds.

- [source code]

Create Dragonfly Buildings from solid geometry (closed Rhino polysurfaces).

Inputs

• bldg_geo [Required]

  A list of closed Rhino polysurfaces to be converted into Buildings.

• floor_to_floor [Required]

  An array of floor-to-floor height instructions that describe how a building mass should be divided into floors. The array should run from bottom floor to top floor. Each item in the array can be either a single number for the floor-to-floor height or a text string that codes for how many floors of each height should be generated. For example, inputting "2@4" will make two floors with a height of 4 units. Simply inputting "@3" will make all floors at 3 units. Putting in sequential arrays of these text strings will divide up floors accordingly. For example, the list ["1@5", "2@4", "@3"] will make a ground floor of 5 units, two floors above that at 4 units and all remaining floors at 3 units.

• perim_offset

  An optional positive number that will be used to offset the perimeter of the footprint to create core/perimeter Rooms. If this value is None or 0, no offset will occur and each floor plate will be represented with a single Room2D.

• name

  Text to set the base name for the Building, which will also be incorporated into unique Building identifier. This will be combined with the index of each input _bldg_geo to yield a unique name for each output Building. If the name is not provided, a random one will be assigned.

• program

  Text for the program of the Buildings (to be looked up in the ProgramType library) such as that output from the "HB List Programs" component. This can also be a custom ProgramType object. If no program is input here, the Buildings will have a generic office program.

• constr_set

  Text for the construction set of the Buildings, which is used to assign all default energy constructions needed to create an energy model. Text should refer to a ConstructionSet within the library such as that output from the "HB List Construction Sets" component. This can also be a custom ConstructionSet object. If nothing is input here, the Buildings will have a generic construction set that is not sensitive to the Buildings's climate or building energy code.

• conditioned

  Boolean to note whether the Buildings have heating and cooling systems.

• run [Required]

  Set to True to run the component and create Dragonfly Buildings.

Outputs

• report

  Reports, errors, warnings, etc.

• buildings

  Dragonfly buildings.

- [source code]

Solve adjacencies between the Room2Ds of Dragonfly objects.

Inputs

• df_objs [Required]

A list of dragonfly Room2Ds for which adjacencies will be solved. This can also be Dragonfly Stories, Buildings or an entire Model, in which case each Story will have adjacencies solved across its Room2Ds.

• adiabatic

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

• air_boundary

Set to True to have all the discovered wall adjacencies set to an AirBoundary type. Note that AirBoundary types are not allowed if interior windows are assigned to interior walls. (Default: False).

• no_overwrite

Boolean to note whether existing Surface boundary conditions should be preserved while solving adjacencies. If True, no intersection will occur and only newly-discovered adjacencies will be updated. If False or unspecified, all geometry will be cleaned and intersected before solving adjacencies. In either case, existing windows will be preserved. Note that, to make use of this option effectively, Room2Ds must already have matching edge segments in order for them to be discovered as adjacent. The "DF Intersect Room2Ds" component can be used to ensure adjacent rooms have matching segments without changing any boundary conditions. (Default: False).

• run [Required]

Set to True to run the component and solve adjacencies.

Outputs

• report

Reports, errors, warnings, etc.

• df_objs

The input Dragonfly objects with adjacencies solved between the Room2D wall segments.

- [source code]

Remove windows from any walls that are within a certain distance of other buildings.

The component can also optionally set the boundary conditions of these walls to adiabatic. This is helpful when attempting to account for alleys or parti walls that may exist between buildings of a denser urban district.

Inputs

• buildings [Required]

Dragonfly Building objects which will have their windows removed if their walls lie within the distance of another building. This can also be an entire Dragonfly Model.

• distance

A number for the maximum distance of an alleyway in Rhino model units. If a wall is closer to another Building than this distance, the windows will be removed. (Default: 1.0 meters).

• adiabatic

A boolean to note whether the walls that have their windows removed should also receive an Adiabatic boundary condition. This is useful when the alleyways are more like parti walls than distinct pathways that someone could traverse.

Outputs

• report

Reports, errors, warnings, etc.

• buildings

The Building objects with their windows removed from any detected alleys.

- [source code]

Separate the top and bottom floors of a Building into unique Stories with a multiplier of 1 and automatically assign the first story Room2Ds to have a ground contact floor and the top story Room2Ds to have an outdoor-exposed roof.

This is particularly helpful when trying to account for the heat exchange of the top or bottom floors with the gound or outdoors.

The "mid" options can also be used to separate the middle floors and account for heat flow through exposed roofs of middle floors.

Inputs

• buildings [Required]

Dragonfly Building objects which will have their top and bottom stories separated into unique ones with a multiplier of 1. This can also be an entire Dragonfly Model.

• sep_mid

Boolean to note whether all mid-level Stories with non-unity multipliers should be separated into two or three Stories. This means that the top of each unique story will have outdoor-exposed roofs when no Room2Ds are sensed above a given room. (Default: False).

• split_mid

Boolean to note whether all mid-level Stories should be split with the Story above in order to set outdoor-exposed roofs with correct areas. This is useful when the Story footprints vary a lot as one moves up the building. An attempt will be made to re-assign properties to the walls of the rooms but some loss of properties like windows is to be expected and may need to be re-assigned. Adjacencies between Room2Ds will be automatically re-solved. This input will have no effect when sep_mid_ is False or unspecified. (Default: False).

Outputs

• buildings

The Building objects with their top and bottom floors separated.

- [source code]

Apply WindowParameters and/or ShadingParameters to any Dragonfly object (Building, Story, Room2D).

Inputs

• df_obj [Required]

A Dragonfly Building, Story or Room2D which will have the input WindowParameters and/or ShadingParameters assigned to it.

• win_par

A WindowParameter object that dictates how the window geometries will be generated for each of the walls. If None, the window parameters will remain unchanged across the input object. If an array of values are input here, different WindowParameters will be assigned based on cardinal direction, starting with north and moving clockwise.

• shd_par

A ShadingParameter objects that dictate how the shade geometries will be generated for each of the walls. If None, the shading parameters will remain unchanged across the input object. If an array of values are input here, different ShadingParameters will be assigned based on cardinal direction, starting with north and moving clockwise.

• skylight

A SkylightParameters object describing how to generate skylights.

Outputs

• report

The execution information, as output and error streams

• df_obj

The input Dragonfly object with the WindowParameters and/or ShadingParameters assigned to it.

-

Create Dragonfly window parameters with instructions for a single window using an area ratio with the base surface.

Inputs

• ratio [Required]

  A number between 0 and 1 for the ratio between the window area and the parent wall surface area.

Outputs

• win_par

  Window Parameters that can be applied to a Dragonfly object using the "DF Apply Facade Parameters" component.

-

Create a Dragonfly Story from individual Dragonfly Room2D objects.

Inputs

• room2ds [Required]

  A list of Dragonfly Story objects to be joined into one Building.

• flr_to_flr

  A number for the distance from the floor plate of this Story to the floor of the story above this one (if it exists). If None, this value will be the maximum floor_to_ceiling_height of the input _room_2ds.

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

• name

  Text to set the name for the Story, which will also be incorporated into unique Story identifier. If the name is not provided a random one will be assigned.

• multiplier

  An integer with that denotes the number of times that this Story is repeated over the height of the building. Default: 1.

• constr_set

  Text for the construction set of the Story, which is used to assign all default energy constructions needed to create an energy model. Text should refer to a ConstructionSet within the library such as that output from the "HB List Construction Sets" component. This can also be a custom ConstructionSet object. If nothing is input here, the Story will have a generic construction set that is not sensitive to the Story's climate or building energy code.

Outputs

• report

  Reports, errors, warnings, etc.

• story

  Dragonfly Building.

-

Create Dragonfly window parameters with instructions for repeating windows derived from an area ratio with the base surface.

Inputs

• ratio [Required]

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

• win_height

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

• sill_height

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

• horiz_separ

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

• vert_separ

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

Outputs

• win_par

  Window Parameters that can be applied to a Dragonfly object using the "DF Apply Facade Parameters" component.

-

Add detailed window geometries to Dragonfly Room2Ds.

Inputs

• df_objs [Required]

A Dragonfly Model, Building, Story or Room2D, to which the _windows should be added.

• windows [Required]

A list of Breps that will be added to the input _df_objs as detailed windows.

Outputs

• df_objs

The input dragonfly objects with the input _windows added to it.

-

Create Dragonfly window parameters with instructions for repeating rectangular windows of a fixed width and height.

This effectively fills a wall with windows at the specified width, height and separation.

Inputs

• win_height

A number for the target height of the windows. Note that, if the window_height is larger than the height of the wall, the generated windows will have a height equal to the wall height in order to avoid having windows extend outside the wall face. (Default: 2 meters).

• win_width

A number for the target width of the windows. Note that, if the window_width is larger than the width of the wall, the generated windows will have a width equal to the wall width in order to avoid having windows extend outside the wall face. (Default: 1.5 meters).

• sill_height

A number for the target height above the bottom edge of the face to start the apertures. Note that, if the window height is too large to acoomodate the sill height input here, the window height will take precedence and the sill height will be smaller than this value. (Default: 0.8 meters).

• horiz_separ

A number for the horizontal separation between individual aperture centerlines. If this number is larger than the parent face's length, only one aperture will be produced. (Default: 3 meters).

Outputs

• win_par

Window Parameters that can be applied to a Dragonfly object using the "DF Apply Facade Parameters" component.

-

Create Dragonfly Buildings from footprint geometry (horizontal Rhino surfaces).

Inputs

• footprint_geo [Required]

A list of horizontal Rhino surfaces or closed planar curves to be converted into Buildings.

• floor_to_floor [Required]

A list of float values with a length equal to the number of stories in each Building. Each value in the list represents the floor_to_floor height of the Story starting from the first floor and then moving to the top floor.

• perim_offset

An optional positive number that will be used to offset the perimeter of the footprint to create core/perimeter Rooms. If this value is None or 0, no offset will occur and each floor plate will be represented with a single Room2D.

• name

Text to set the base name for the Building, which will also be incorporated into unique Building identifier. This will be combined with the index of each input _footprint_geo to yield a unique name for each output Building. If the name is not provided, a random one will be assigned.

• program

Text for the program of the Buildings (to be looked up in the ProgramType library) such as that output from the "HB List Programs" component. This can also be a custom ProgramType object. If no program is input here, the Buildings will have a generic office program.

• constr_set

Text for the construction set of the Buildings, which is used to assign all default energy constructions needed to create an energy model. Text should refer to a ConstructionSet within the library such as that output from the "HB List Construction Sets" component. This can also be a custom ConstructionSet object. If nothing is input here, the Buildings will have a generic construction set that is not sensitive to the Buildings's climate or building energy code.

• conditioned

Boolean to note whether the Buildings have heating and cooling systems.

• run [Required]

Set to True to run the component and create Dragonfly Buildings.

Outputs

• report

Reports, errors, warnings, etc.

• buildings

Dragonfly buildings.

- [source code]

Create Dragonfly skylight parameters with instructions for generating skylights according to a ratio with the base Roof surface.

Inputs

• ratio [Required]

A number between 0 and 0.75 for the ratio between the skylight area and the total Roof face area.

• spacing

A number for the spacing between the centers of each grid cell. This should be less than half of the dimension of the Roof geometry if multiple, evenly-spaced skylights are desired. If None, a spacing of one half the smaller dimension of the parent Roof will be automatically assumed. (Default: None).

Outputs

• skylight

Skylight Parameters that can be applied to a Dragonfly object using the "DF Apply Facade Parameters" component.

-

Create Dragonfly shading parameters with instructions for extruded borders over all windows.

Inputs

• depth [Required]

  A number for the depth of the extruded border.

Outputs

• shd_par

  Shading Parameters that can be applied to a Dragonfly object using the "DF Apply Facade Parameters" component.

-

Create Dragonfly ContextShade.

Inputs

• geo [Required]

Rhino Brep geometry.

• name

A name for the ContextShade. If the name is not provided a random name will be assigned.

• ep_constr

Optional text for the ContextShade's energy construction to be looked up in the construction library. This can also be a custom construction object. If no energy construction is input here, a default will be assigned.

• ep_trans_sch

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

• uwg_is_veg

Boolean to note whether the shade represents a tree canopy within simulations with the Urban Weather Generator (UWG), in which case, it will be incorporated into the simulation as tree cover. NOTE that, when using this option, only the tops and sides of the tree canopy geometry should be modeled. Modeling the bottom of the tree canopy will result in double-counting the horizontal area of the canopy and will also create extra unnessary geometry in EnergyPlus or Radiance calculations using the dragonfly model. (Default: False).

Outputs

• report

Reports, errors, warnings, etc.

• context

Dragonfly ContextShades.

-

Create Dragonfly shading parameters with instructions for a single overhang (awning, balcony, etc.) over an entire wall.

Inputs

• depth [Required]

  A number for the overhang depth.

• angle

  A number for the for an angle to rotate the overhang in degrees. Default is 0 for no rotation.

Outputs

• shd_par

  Shading Parameters that can be applied to a Dragonfly object using the "DF Apply Facade Parameters" component.

-

Deconstruct any Dragonfly Story, Building or Model to get the Roof geometry.

This is useful for checking the roof geometry assigned to sotries and possbily editing it so that it can be re-assigned with "DF Apply Roof" component.

Inputs

• df_obj [Required]

A Dragonfly Model, Building, Story for which the roof geometry will be extracted.

Outputs

• stories

The unique Story objects that make up the input _df_obj. This is typically a data tree with branches coordinated with the roof_geo below.

• roof_geo

A list of Breps representing the geometry of the Roof. This is often a data tree with one branch for each story, which is coordinated with the stories above.

-

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

This is particularly useful for cleaning up models with extra unwanted corrugations in them around columns and other "room bounding" elements.

Note that, when there are small Room2Ds next to the input lines, this component may completely remove the small Room2D if it becomes degenerate.

Inputs

• df_obj [Required]

A Dregonfly Story, Building or Model to be aligned to the input lines. For Buildings and Models, all Room2Ds across the object will be aligned.

• lines [Required]

A list of straignt lines to which the Room2D vertices will be aligned.

• distance

The maximum distance between a vertex and a line where the vertex will be moved to lie on the line. Vertices beyond this distance will be left as they are. The default is 0.5 meters.

Outputs

• df_obj

The input Dragonfly objects with Room2Ds that have been aligned to the input lines.

-

Assign Roof geometry to a Dragonfly Story, Building, or Model.

This can be used to generate sloped roofs over a Story. The roof geometry will only affect the 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.

Multiple sucessive versions of this component can be used to assign different roof specifications for different Stories of a Dragonfly Building or Model.

Inputs

• df_obj [Required]

A Dregonfly Story or Building to which the roof geometry is assigned. When a building is plugged in, only one story will receive the roof geometry, which will be the top floor unless an explicit story_i is specified below. This input can also be an entire Dragonfly Model, in which case the relevant Story of the first Building will receive the roof geometry, indicating that a Model inputs are really only appropriate when the Model contains one Building.

• roof_geo [Required]

A list of Breps representing the geometry of the Roof. Together, these Breps should completely cover the Room2Ds of the Story to which they are assigned.

• story_i

An optional integer to set the index of the Story to which the Roof should be assigned. If unspecified, the roof geometry will be added to the top floor of any connected Building or Model.

Outputs

• df_obj

The input Dragonfly objects with the roof geometry assigned to them.

-

Make boundary conditions of Dragonfly Room2Ds Adiabatic or Ground by oreintation.

Note that this component will remove windows for any wall segment that is set to have an Adiabatic or Ground boundary condition.

Inputs

• df_obj [Required]

  A Dragonfly Building, Story or Room2D which will have boundary conditions assigned to its walls according to the inputs below.

• adiabatic

  A list of Booleans to denote whether exterior walls of a given orientation should be set to adiabatic. Different adiabatic values will be assigned based on the cardinal direction, starting with north and moving clockwise. The "HB Facade Parameters" component can be used to order this list correctly for four main orientations.

• ground

  A list of Booleans to denote whether exterior walls of a given orientation should be set to ground. Different ground values will be assigned based on the cardinal direction, starting with north and moving clockwise. The "HB Facade Parameters" component can be used to order this list correctly for four main orientations.

Outputs

• df_obj

  The input Dragonfly object with the wall boundary conditions changed.

- [source code]

Create Dragonfly shading parameters with instructions for a series of louvered Shades over a Wll.

Inputs

• depth [Required]

  A number for the depth to extrude the louvers.

• shade_count

  A positive integer for the number of louvers to generate. Note that this input should be None if there is an input for dist_between. Default: 1.

• dist_between

  A number for the approximate distance between each louver. Note that this input should be None if there is an input for shade_count.

• facade_offset

  A number for the distance to louvers from the Wall. Default is 0 for no offset.

• angle

  A number for the for an angle to rotate the louvers in degrees. Default is 0 for no rotation.

• vertical

  Optional boolean to note whether the lovers are vertical. If False, the louvers will be horizontal. Default False.

• flip_start

  Boolean to note whether the side the louvers start from should be flipped. Default is False to have contours on top or right. Setting to True will start contours on the bottom or left.

Outputs

• shd_par

  Shading Parameters that can be applied to a Dragonfly object using the "DF Apply Facade Parameters" component.

- [source code]

Preview any Dragonfly geometry object as floor plates within the Rhino scene, including all stories represented by multipliers

Inputs

• df_objs [Required]

A Dragonfly Model, Building, Story, Room2D, or ContextShade to be previewed as a list of floor plates in the Rhino scene.

Outputs

• geo

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

• Visualize All

• Visualize Floors

• Visualize Quick

• Visualize Wireframe

• Geometry Properties

• Room2D Attributes

• Color Room2D Attributes

• Room2Ds by Attribute

• Color Network Attributes

• Network Attributes

• Color Network Results

- [source code]

Preview any Dragonfly geometry object within the Rhino scene, including all stories represented by multipliers

Inputs

• df_objs [Required]

A Dragonfly Model, Building, Story, Room2D, or ContextShade to be previewed in the Rhino scene.

Outputs

• geo

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

-

Quickly preview any Dragonfly geometry object within the Rhino scene.

Any stories represented by multipliers will not be included in the output, allowing for a faster preview of large lists of objects but without the ability to check the multipliers of objects.

Inputs

• df_objs [Required]

A Dragonfly Model, Building, Story, Room2D, or ContextShade to be previewed in the Rhino scene.

Outputs

• geo

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

- [source code]

Set Room2Ds or Stories to have their floor in contact with the ground or their roofs in contact with the outdoors.

Inputs

• df_obj [Required]

  Dragonfly Stories or Room2Ds which will have its floor set to be in contact with the ground or its roof to be in contact with the outdoors.

• grnd_contact

  A boolean noting whether the input objects have floors in contact with the ground.

• top_exposed

  A boolean noting whether the input objects have ceilings exposed to the outdoors.

Outputs

• report

  Reports, errors, warnings, etc.

• df_obj

  The input Dragonfly object with its ground_contact or top_exposed properties edited.

- [source code]

Take a list of Dragonfly Room2Ds and split their adjacent Walls to ensure that there are matching segments between each of the adjacent Room2Ds.

Note that this component effectively erases all assigned boundary conditions, glazing parameters and shading parameters as the original segments are subdivided. As such, it is recommended that this component be used before all other steps when creating a Story.

Also note that this component does not actually set the walls that are next to one another to be adjacent. The "DF Solve Adjacency" component must be used for this after runing this component.

Inputs

• room2ds [Required]

  A list of Room2Ds for which adjacencent segments will be intersected.

• run [Required]

  Set to True to run the component.

Outputs

• int_room2ds

  An array of Room2Ds that have been intersected with one another. Note that these Room2Ds lack all assigned boundary conditions, glazing parameters and shading parameters of the original Room2Ds.

- [source code]

Create Dragonfly window parameters with instructions for a single window in the face center defined by a width and height.

Note that, if these parameters are applied to a base face that is too short or too narrow for the input width and/or height, the generated window will automatically be shortened when it is applied to the face. In this way, setting the width to be a very high number will create parameters that always generate a ribboin window of the input height.

Inputs

• width [Required]

  A number for the window width.

• height [Required]

  A number for the window height.

• sill_height

  A number for the window sill height. Default: 0.8 meters.

Outputs

• win_par

  Window Parameters that can be applied to a Dragonfly object using the "DF Apply Facade Parameters" component.

- [source code]

Provides a list of dragonfly Room2D properties.

- [source code]

Get properties of any Dragonfly geometry object.

Inputs

• df_objs [Required]

  A Dragonfly Model, Building, Story or Room2D for which properties will be output.

Outputs

• height

  For a Model or a Building, this will be the average height of the object above the ground. For a Story, this will be the floor-to-floor height and, for a Room2D, this will be the floor-to-ceiling height.

• floor_area

  A number for the floor area of all Rooms in the dragonfly object.

• ext_wall_area

  A number for the total area of walls in the dragonfly object with an Outdoors boundary condition.

• ext_win_area

  A number for the total area of windows in the dragonfly object with an Outdoors boundary condition.

• volume

  A number for the volume of all Rooms in the dragonfly object.

- [source code]

Quickly preview any Dragonfly geometry object as a wire frame within the Rhino scene, including all stories represented by multipliers

Inputs

• df_objs [Required]

A Dragonfly Model, Building, Story, Room2D, or ContextShade to be previewed as a wire frame in the Rhino scene.

Outputs

• geo

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

-

Separate and group dragonfly Room2Ds by any attribute that the room possesses.

This can be used to group Room2Ds by program, whether rooms are conditioned, etc.

Inputs

• df_obj [Required]

  A Dragonfly Model, Building, Story or Room2D to be separated and grouped based on room attributes.

• attribute [Required]

  Text for the name of the Room2D attribute by which the Room2Ds should be separated. The "DF Room2D Attributes" component lists all of the attributes of the Room2D.

Outputs

• values

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

• room2ds

  A data tree of honeybee rooms with each branch of the tree representing a different attribute value.

- [source code]

Color Dragonfly Room2Ds in the Rhino scene using their attributes.

This can be used as a means to check that correct properties are assigned to different Room2Ds.

Inputs

• df_obj [Required]

A Dragonfly Model, Building, Story or Room2D to be colored with their attributes in the Rhino scene.

• attribute [Required]

Text for the name of the Room2D attribute with which the Room2Ds should be colored. The "DF Room2D Attributes" component lists all of the attributes of the Room2D.

• legend_par

An optional LegendParameter object to change the display of the colored Room2Ds. (Default: None).

Outputs

• mesh

Meshes of the Room2D floors colored according to their attributes.

• legend

Geometry representing the legend for colored meshes.

• wire_frame

A list of lines representing the outlines of the rooms.

• values

A list of values that align with the input Room2Ds noting the attribute assigned to each Room2D.

• colors

A list of colors that align with the input Room2Ds, noting the color of each Room2D in the Rhino scene. This can be used in conjunction with the native Grasshopper "Custom Preview" component and other dragonfly visualization components (like "DF Visulaize All") to create custom visualizations in the Rhino scene.

-

Color a Dragonfly ElectricalNewtwork in the Rhino scene with OpenDSS simulation results.

Inputs

• data [Required]

A list of data collections of the same data type, which will be used to color the network with simulation results. These should come from the "DF Read OpenDSS Result" component.

• network [Required]

A Dragonfly Electrical Newtork object to be colored with results in the Rhino scene.

• sim_step

An optional integer (greater than or equal to 0) to select a specific step of the data collections for which result values will be generated. If None, the geometry will be colored with the maximum of resutls in the _data, essentially describing the peak condition. (Default: None).

• period

A Ladybug analysis period to be applied to all of the input _data.

• legend_par

An optional LegendParameter object to change the display of the colored output. (Default: None).

Outputs

• vis_geo

Meshes and line segments colored according to the results.

• legend

Geometry representing the legend for colored objects.

• title

A text object for the global title.

• values

A list of values that align with the input substation, transformers and electrical connectors. These note the value assigned to each object.

• colors

A list of colors that align with the input substation, transformers and electrical connectors. These note the color of each object in the Rhino scene.

-

Color a Dragonfly ElectricalNewtwork in the Rhino scene using its attributes.

This can be used as a means to check that correct properties are assigned to different Transformers and ElectricalConnectors.

Inputs

• network [Required]

A Dragonfly Electrical Newtork object to be colored with its attributes in the Rhino scene.

• attribute [Required]

Text for the name of the equipment attribute with which the Newtork should be colored. The "DF Network Attributes" component lists all of the attributes of the equipment of an ElectricalNetwork.

• legend_par

An optional LegendParameter object to change the display of the colored output. (Default: None).

Outputs

• vis_geo

Meshes and line segments colored according to their attributes.

• legend

Geometry representing the legend for colored objects.

• values

A list of values that align with the input substation, transformers and electrical connectors. These note the attribute assigned to each object.

• colors

A list of colors that align with the input substation, transformers and electrical connectors. These note the color of each object in the Rhino scene.

-

Serialize any dragonfly JSON text string back to a dragonfly object.

This includes any Model, Building, Story, Room2D, WindowParameter, or ShadingParameter.

It also includes any dragonfly energy Material, Construction, ConstructionSet, Schedule, Load, ProgramType, or Simulation object.

Inputs

• df_str [Required]

  A text string that completely describes the dragonfly object.

Outputs

• df_obj

  A Dragonfly object serialized from the input string.

- [source code]

Load any dragonfly object from a dragonfly JSON file

This includes any Model, Building, Story, Room2D, WindowParameter, or ShadingParameter.

It also includes any energy Material, Construction, ConstructionSet, Schedule, Load, ProgramType, or Simulation object.

Inputs

• df_file [Required]

  A file path to a dragonfly JSON from which objects will be loaded back into Grasshopper. The objects in the file must be non-abridged in order to be loaded back correctly.

• load [Required]

  Set to "True to load the objects from the _df_file.

Outputs

• report

  ...

• df_objs

  A list of dragonfly objects that have been re-serialized from the input file.

- [source code]

Provides a list of dragonfly electrical network properties.

• Object to String

• String to Object

• Dump Objects

• Load Objects

• Model To Honeybee

• Model To geoJSON

• Model From Honeybee

• Model From geoJSON

• Validate Model

-

Convert a Dragonfly Model into a series of Honeybee Models.

Inputs

• model [Required]

A Dragonfly Model object.

• obj_per_model

Text to describe how the input Buildings should be divided across the output Models. Default: 'Building'. Choose from the following options:

• use_multiplier

If True, the multipliers on each Building's Stories will be passed along to the generated Honeybee Room objects, indicating the simulation will be run once for each unique room and then results will be multiplied. If False, full geometry objects will be written for each and every story in the building such that all resulting multipliers will be 1. (Default: True).

• add_plenum

Boolean to indicate whether ceiling/floor plenums should be auto-generated for the Rooms. The height of ceiling plenums will be autocalculated as the difference between the Room2D ceiling height and Story ceiling height. The height of the floor plenum will be autocalculated as the difference between the Room2D floor height and Story floor height. (Default: False).

• ceil_adjacency

Boolean to note whether adjacencies should be solved between interior stories when Room2Ds perfectly match one another in their floor plate. This ensures that Surface boundary conditions are used instead of Adiabatic ones. Note that this input has no effect when the obj_per_model is Story. (Default: False).

• cap_shades

Boolean to note whether building shade representations 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).

• shade_dist

An optional number to note the distance beyond which other buildings' shade should not be exported into a given Model. This is helpful for reducing the simulation run time of each Model when other connected buildings are too far away to have a meaningful impact on the results. If None, all other buildings will be included as context shade in each and every Model. Set to 0 to exclude all neighboring buildings from the resulting models. Default: None.

• run [Required]

Set to "True" to have the Dragonfly Model translated to a series of Honeybee Models.

Outputs

• report

Reports, errors, warnings, etc.

• hb_models

Honeybee Model objects derived from the input _models. These Models are ready to be simulated in either an Energy or Radiance simulation or they can be edited further with the Honeybee components.

- [source code]

Convert a Dragonfly Model into an URBANopt-compatible geoJSON with linked Honeybee Model JSONs. Honeybee Model JSONs will be referenced using the "detailed_model_filename" key in the geoJSON.

Inputs

• model [Required]

A Dragonfly Model object.

• location [Required]

A ladybug Location object possessing longitude and lattiude data used to position geoJSON file on the globe.

• point

A Point for where the _location object exists within the space of the Rhino scene. This is used to posistion the geoJSON file on the globe. (Default: Rhino origin (0, 0, 0)).

• use_multiplier

If True, the multipliers on each Building's Stories will be passed along to the generated Honeybee Room objects, indicating the simulation will be run once for each unique room and then results will be multiplied. If False, full geometry objects will be written for each and every story in the building such that all resulting multipliers will be 1. Default: True.

• add_plenum

Boolean to indicate whether ceiling/floor plenums should be auto-generated for the Rooms. The height of ceiling plenums will be autocalculated as the difference between the Room2D ceiling height and Story ceiling height. The height of the floor plenum will be autocalculated as the difference between the Room2D floor height and Story floor height. (Default: False).

• ceil_adjacency

Boolean to note whether adjacencies should be solved between interior stories when Room2Ds perfectly match one another in their floor plate. This ensures that Surface boundary conditions are used instead of Adiabatic ones. (Default: False).

• shade_dist

An optional number to note the distance beyond which other buildings' shade should not be exported into a given Model. This is helpful for reducing the simulation run time of each Model when other connected buildings are too far away to have a meaningful impact on the results. If None, all other buildings will be included as context shade in each and every Model. Set to 0 to exclude all neighboring buildings from the resulting models. Default: None.

• des_loop

An optional District Energy System (DES) ThermalLoop that's associated with the dragonfly Model.

• network

An optional OpenDSS ElectricalNetwork or RNM RoadNetwork that's associated with the input Dragonfly Model and will be written into the geoJSON. An input here is required to perform an OpenDSS or RNM simulation after running URBANopt.

• ground_pv

An optional list of REopt GroundMountPV objects representing ground-mounted photovoltaic fields to be included in a REopt simulation after running URBANopt.

• folder

Text for the full path to the folder where the geojson will be written along with all of the Honeybee Model JSONs. If None, the honeybee default simulation folder is used.

• write [Required]

Set to "True" to have the Dragonfly Model translated to an URBANopt-compatible geoJSON. This input can also be the integer "2", which will only create the geojson file but not create any honeybee Model json files that are linked to it (note that a geojson produced this way is not compatible with URBANopt).

Outputs

• report

Reports, errors, warnings, etc.

• geojson

The path to a geoJSON file that contains polygons for all of the Buildings within the dragonfly model along with their properties (floor area, number of stories, etc.). The polygons will also possess detailed_model_filename keys that align with where the Honeybee Model JSONs are written.

• net_json

A JSON file containing a representation of the electrical or street network. This can be loaded back to the original object using the "DF Load Objects" component. This will be None if no network_ is connected.

• hb_jsons

A list of file paths to honeybee Model JSONS that correspond to the detailed_model_filename keys in the geojson.

• hb_models

A list of honeybee Model objects that were generated in process of writing the URBANopt files. These can be visulazed using the components in the Honeybee 1 :: Visualize tab in order to verify that properties have been translated as expected.

- [source code]

Dump any dragonfly object to a JSON file. You can use "DF Load Objects" component to load the objects from the file back into Grasshopper.

This includes any Model, Building, Story, Room2D, WindowParameter, or ShadingParameter.

It also includes any energy Material, Construction, ConstructionSet, Schedule, Load, ProgramType, or Simulation object.

Inputs

• df_objs [Required]

  A list of Dragonfly objects to be written to a file.

• name

  A name for the file to which the dragonfly objects will be written. (Default: 'unnamed').

• folder

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

• indent

  An optional positive integer to set the indentation used in the resulting JSON file.

• abridged

  Set to "True" to serialize the object in its abridged form. Abridged objects cannot be reserialized back to dragonfly objects on their own but they are used throughout dragonfly to minimize file size and unnecessary duplication.

• dump [Required]

  Set to "True" to save the dragonfly objects to file.

Outputs

• report

  Errors, warnings, etc.

• df_file

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

- [source code]

Create a Dragonfly Model from a Honeybee Model.

Inputs

• hb_models [Required]

A Honeybee Model or list of Honeybee Models to be converted to a Dragonfly Model.

• incl_shades

Boolean to note whether orphaned shades should be included as dragonfly ContextShades. (Default: False).

• load [Required]

Set to "True to load the objects from the _df_file.

Outputs

• report

...

• df_model

A list of dragonfly objects that have been re-serialized from the input file.

- [source code]

Get a validation report that contains a summary of all issues with the Model.

This includes checks for basic properties like adjacency as well as geometry checks.

Inputs

• model [Required]

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

• validate [Required]

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

Outputs

• report

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

- [source code]

Create a Dragonfly Model from a geoJSON file.

Inputs

• geojson [Required]

  Text for the full path to a geojson file to be loaded as a Dragonfly Model.

• point

  An optional Point for where the bottom-left corner of the bounding rectangle around all of the geoJSON building footprints exists within the Rhino scene. (Default: (0, 0), the Rhino origin).

• all_to_bldg

  Boolean to indicate if all polygon and multi-polygon geometries in the geojson file should be considered Buildings. If False or unspecified, this component will only generate Dragonfly Buildings from geometries that are defined as a 'Building' in the 'type' field of the 'properties' field of each geoJSON feature. Note that this 'type' field is not a universal convention of all geoJSONs. However, all Dragonfly-expored geoJSONs will have it and all URBANopt-compatible geoJSONs will also have it.

• other_geo

  Boolean to indicate whether geometry that is not identified as a dragonfly Building should be imported. For large geoJSONs, this can potentially increase the component runtime a lot but this geometry may be useful for constructing other important features like context or electical networks.

• import [Required]

  Set to "True" to import the geoJSON as a Dragonfly Model.

Outputs

• report

  Reports, errors, warnings, etc.

• model

  A Dragonfly Model object derived from the input geoJSON.

• other_geo

  Other non-building line segment and polygon data contained within the geoJSON. Will be None unless othergeo is set to True.

• location

  A ladybug Location object possessing longitude and lattiude data used to position geoJSON file on the globe.

• point

  A Point for where the _location object exists within the space of the Rhino scene. This is can be used to re-position the geoJSON file on the globe when re-exporting the Dragonfly Model to geoJSON.

-

Serialize any dragonfly object to a JSON text string. You can use "DF String to Object" component to load the objects from the file back.

This includes any Model, Building, Story, Room2D, WindowParameter, or ShadingParameter.

It also includes any honeybee energy Material, Construction, ConstructionSet, Schedule, Load, ProgramType, or Simulation object.

Inputs

• df_obj [Required]

  A Dragonfly object to be serialized to a string.

Outputs

• df_str

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

-

Run an URBANopt geoJSON through EnergyPlus using the URBANopt CLI.

This component requires the URBANopt CLI to be installed in order to run. Installation instructions for the URBANopt CLI can be found at: https://docs.urbanopt.net/installation/installation.html

Inputs

• geojson [Required]

The path to an URBANopt-compatible geoJSON file. This geoJSON file can be obtained form the "DF Model to geoJSON" component.

• epw_file [Required]

Path to an .epw file on this computer as a text string.

• sim_par

A honeybee Energy SimulationParameter object that describes all of the settings for the simulation. If None, some default simulation parameters will be automatically generated.

• measures

An optional list of measures to apply to the OpenStudio model upon export. Use the "HB Load Measure" component to load a measure into Grasshopper and assign input arguments. Measures can be downloaded from the NREL Building Components Library (BCL) at

• mappers

An optional list of dragonfly MapperMeasure objects to be included in the output osw. MapperMeasures are just like normal OpenStudio measures except they can accept a list of values for their arguments that align with the buildings in dragonfly Model. Each value in the list will be mapped to a different building.

• report

Boolean to note whether to include the URBANopt default feature reporting measure as part of the simulation. If True, the measure will be run after all simulations are complete. (Default:True).

• emiss_yr

An optional integer to set the year for which carbon emissions will be computed. Values must be an even number and be between 2020 and 2050. If unspecified, no carbon emission calculations will be included in the simulation. After the simulation is run, the hourly carbon emissions can be imported from the output sql files by using the "HB Read Custom Result" component and plugging in the following output name: Future_Hourly_Electricity_Emissions

• cpus

A positive integer for the number of CPUs to use in the simulation. This number should not exceed the number of CPUs on the machine running the simulation and should be lower if other tasks are running while the simulation is running. If set to None, it should automatically default to one less than the number of CPUs currently available on the machine (or 1 if the machine has only one processor). (Default: None).

• run [Required]

Set to "True" to run the geojson through URBANopt. This will ensure that all result files appear in their respective outputs from this component. This input can also be the integer "2", which will only run the setup of the URBANopt project folder (including the creation of the scenario file) but will not execute the simulations.

Outputs

• out

Reports, errors, warnings, etc.

• scenario

File path to the URBANopt scenario CSV used as input for the URBANopt CLI run.

• osm

File paths to the OpenStudio Models (OSM) that were generated in the process of running URBANopt.

• idf

File paths to the EnergyPlus Input Data Files (IDF) that were generated in the process of running URBANopt.

• sql

List of paths to .sqlite files containing all simulation results.

• zsz

List of paths to .csv files containing detailed zone load information recorded over the course of the design days.

• rdd

File paths of the Result Data Dictionary (.rdd) that were generated after running the file through EnergyPlus. This file contains all possible outputs that can be requested from the EnergyPlus model. Use the "Read Result Dictionary" component to see what outputs can be requested.

• html

File paths of the HTMLs containting all Summary Reports.

- [source code]

Run a an URBANopt geoJSON and scenario through REopt using the URBANopt CLI.

This component requires the URBANopt CLI to be installed in order to run. Installation instructions for the URBANopt CLI can be found at: https://docs.urbanopt.net/installation/installation.html

Inputs

• geojson [Required]

The path to an URBANopt-compatible geoJSON file. This geoJSON file can be obtained form the "DF Model to geoJSON" component.

• scenario [Required]

The path to an URBANopt .csv file for the scenario. This CSV file can be obtained form the "DF Run URBANopt" component.

• urdb_label [Required]

Text string for the Utility Rate Database (URDB) label for the particular electrical utility rate for the optimization. The label is the last term of the URL of a utility rate detail page (eg. the urdb label at https://openei.org/apps/IURDB/rate/view/5b0d83af5457a3f276733305 is 5b0d83af5457a3f276733305). Utility rates for specific locations can be looked up in the REopt Lite tool (https://reopt.nrel.gov/tool) and the label can be obtained by clicking on "Rate Details" link for a particular selected rate.

• financial_par

A REoptParameter object to describe the financial assumptions of the REopt analysis. This can be obtained from the "DF REopt Financial Parameters" component. If None, some default parameters will be generated for a typical analysis. (Default: None).

• wind

A number for the maximum installed kilowatts of wind power. (Default: 0).

• pv

A number for the maximum installed kilowatts of roof-mounted photovoltaic power. (Default: 1000000000).

• pv_ground

A number for the maximum installed kilowatts of ground-mounted photovoltaic power. (Default: 1000000000).

• storage

A number for the maximum installed kilowatts of electrical storage. (Default: 1000000).

• generator

A number for the maximum installed kilowatts of generator power. Note that generators are only used in outages. (Default: 1000000000).

• run [Required]

Set to "True" to run the geojson and scenario through REopt. This will ensure that all result files appear in their respective outputs from this component.

Outputs

• report

Reports, errors, warnings, etc.

• values

A list of numerical values from the REopt analysis, all related to the cost and financial outcome of the optimization. These values align with the parameters below.

• parameters

A list of text that correspond to the numerical values above. Each text item explains what the numerical value means.

• wind

A number for the optimal capacity of wind power that should be installed in kW. This will be null unless a non-zero value is specified for the input wind.

• pv

A number for the optimal capacity of roof-mounted photovlotaic power that should be installed in kW.

• pv_ground

A number for the optimal capacity of ground-mounted photovlotaic power that should be installed in kW.

• storage

A list of two numbers ordered as follows.

- A number for the optimal dicharge capacity of battery storagethat should be installed in kW. 


- A number for the optimal total capacity of battery storagethat should be installed in kWh. 

• generator

A number for the optimal capacity of generator power that should be installed in kW. This will be null unless a non-zero value is specified for the input generator.

• data

A list of hourly continuous data collections containing the detailed timeseties results of the REopt analysis.

- [source code]

Load OpenStudio measures into Grasshopper and assign the measure's input arguments in a manner that can be mapped to different buildings in a Dragonfly model.

The resulting measure object can be plugged into the "measures_" input of the "DF Run URBANopt" component in order to be included in the simulation.

Inputs

• measure_path [Required]

  Path to the folder in which the measure exists. This folder must contain a measure.rb and a measure.xml file. Note that connecting an input here will transform the component, essentially removing this input and changing all of the other component inputs to be input arguments for the measure.

Outputs

• report

  The execution information, as output and error streams

• mapper

  A mapper measure object can be plugged into the "measures_" input of the "DF Run URBANopt" component in order to be included in the simulation.

- [source code]

Diversify the ProgramTypes assigned to a Building's Room2Ds.

This is useful when attempting to account for the fact that not all rooms are used by occupants according to a strict scheduled regimen. Some rooms will be used more than expected and others less.

This component uses a random number generator and gaussian distribution to generate loads that vary about the original "mean" programs. Note that the randomly generated values assigned by this component will be different every time that this component is run unless and input for seed_ has been specified.

In addition to diversifying load values, approximately 2/3 of the schedules in the resulting Room2Ds will be offset from the mean by the input schedule_offset (1/3 ahead and another 1/3 behind).

Inputs

• building [Required]

  A Dragonfly Building, which will have its room programs diversified.

• occ_stdev

  A number between 0 and 100 for the percent of the occupancy people_per_area representing one standard deviation of diversification from the mean. (Default 20 percent).

• lighting_stdev

  A number between 0 and 100 for the percent of the lighting watts_per_area representing one standard deviation of diversification from the mean. (Default 20 percent).

• electric_stdev

  A number between 0 and 100 for the percent of the electric equipment watts_per_area representing one standard deviation of diversification from the mean. (Default 20 percent).

• gas_stdev

  A number between 0 and 100 for the percent of the gas equipment watts_per_area representing one standard deviation of diversification from the mean. (Default 20 percent).

• hot_wtr_stdev

  A number between 0 and 100 for the percent of the service hot water flow_per_area representing one standard deviation of diversification from the mean. (Default 20 percent).

• infilt_stdev

  A number between 0 and 100 for the percent of the infiltration flow_per_exterior_area representing one standard deviation of diversification from the mean. (Default 20 percent).

• sched_offset

  A positive integer for the number of timesteps at which all schedules of the resulting programs will be shifted - roughly 1/3 of the programs ahead and another 1/3 behind. (Default: 1).

• timestep

  An integer for the number of timesteps per hour at which the shifting is occurring. This must be a value between 1 and 60, which is evenly divisible by 60. 1 indicates that each step is an hour while 60 indicates that each step is a minute. (Default: 1).

• seed

  An optional integer to set the seed of the random number generator that is diversifying the loads. Setting a value here will ensure that the same "random" values are assigned every time that this component is run, making comparison of energy simulation results easier. If not set, the loads assigned by this component will be different every time it is run.

Outputs

• building

  The input Dragonfly Building with its programs diversified. The diversified values can be checked by using the "DF Color Room2D Attributes" component.

- [source code]

Run a an URBANopt geoJSON and scenario through OpenDSS.

The geoJSON must have a valid Electrical Network assigned to it in order to run correctly through OpenDSS.

Inputs

• geojson [Required]

The path to an URBANopt-compatible geoJSON file. This geoJSON file can be obtained form the "DF Model to geoJSON" component. The geoJSON must have a valid Electrical Network assigned to it in order to run correctly through OpenDSS.

• scenario [Required]

The path to an URBANopt .csv file for the scenario. This CSV file can be obtained form the "DF Run URBANopt" component.

• run_period

A ladybyg AnalysisPeriod object to describe the time period over which to run the simulation. The default is to run the simulation for the whole EnergyPlus run period.

• autosize

A boolean to note whether undersized transformers should be automatically resized to meet demand over the course of the simulation. (Default: False).

• run [Required]

Set to "True" to run the geojson and scenario through OpenDSS.

Outputs

• report

Reports, errors, warnings, etc.

• buildings

A list of CSV files containing the voltage and over/under voltage results of the simulation at each timestep. There is one CSV per building in the dragonfly model. These can be imported with the "DF Read OpenDSS Result" component.

• connectors

A list of CSV result files containing the power line loading and overloading results of the simulation at each timestep. There is one CSV per electrical connector in the network. These can be imported with the "DF Read OpenDSS Result" component.

• transformers

A list of CSV result files containing the transformer loading and overloading results of the simulation at each timestep. There is one CSV per transformer in the network. These can be imported with the "DF Read OpenDSS Result" component.

-

Re-assign energy properties to any Dragonfly object (Building, Story, Room2D, Model).

This is useful for editing auto-generated child objects separately from their parent. For example, if you want to assign all of the ground floors of a given auto-generated Building to have a Retail ProgramType, this can help re-assign a Retail ProgramType to such stories.

Inputs

• df_obj [Required]

A Dragonfly Building, Story or Room2D which is to have its energy properties re-assigned. This can also be an entire Dragonfly Model.

• program

Text to reassign the program of the input objects (to be looked up in the ProgramType library) such as that output from the "HB List Programs" component. This can also be a custom ProgramType object.

• constr_set

Text to reassign construction set of the input objects, which is usedto assign all default energy constructions needed to create an energy model. Text should refer to a ConstructionSet within the library such as that output from the "HB List Construction Sets" component. This can also be a custom ConstructionSet object.

Outputs

• df_obj

The input Dragonfly object with its properties re-assigned based on the input.

- [source code]

Run a an URBANopt geoJSON and scenario through RNM.

The geoJSON must have a valid Road Network assigned to it in order to run correctly through RNM.

Inputs

• geojson [Required]

The path to an URBANopt-compatible geoJSON file. This geoJSON file can be obtained form the "DF Model to geoJSON" component. The geoJSON must have a valid Road Network assigned to it in order to run correctly through RNM.

• scenario [Required]

The path to an URBANopt .csv file for the scenario. This CSV file can be obtained form the "DF Run URBANopt" component.

• ug_ratio

A number between 0 and 1 for the ratio of overall cables that are underground vs. overhead in the analysis. (Default: 0.9).

• include_hv

A boolean to note whether high voltage consumers should be included in the analysis. (Default: False).

• nodes_per_bldg

A positive integer for the maximum number of low voltage nodes to represent a single building. (Default: 1).

• run [Required]

Set to "True" to run the geojson and scenario through RNM.

Outputs

• report

Reports, errors, warnings, etc.

• network

The ElectricalNetwork object output from the RNM simulation. The properties of this object can be visualized with the "DF Color Network Attributes" component. However, the network can not be used for OpenDSS simulation (the dss_files below should be used for this purpose).

• dss_results

Path to the folder containing all of the OpenDSS files.

-

Apply a Dedicated Outdoor Air System (DOAS) template HVAC to a list of Dragonfly Buildings, Stories or Room2Ds.

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

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

Inputs

• df_objs [Required]

  Dragonfly Buildings, Stories or Room2Ds to which the input template HVAC will be assigned. If a list of Room2Ds is input, all objects will receive the same HVAC instance. Otherwise, each object gets its own instance (eg. each input Story will get its own HVAC). This can also be an etire dragonfly Model.

• system_type [Required]

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

• vintage

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

• name

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

• sensible_hr

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

• latent_hr

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

• dcv

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

• doas_avail_sch

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

Outputs

• report

  Script variable OSHVACSystems

• df_objs

  The input Dragonfly objects with a DOAS HVAC system applied.

-

Apply process loads to a Dragonfly Room2D or all Room2Ds of a Dragonfly Story, Building or Model.

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

Inputs

• df_obj [Required]

A Dragonfly Room2D, Story or Building to which process loads should be assigned.

• name

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

• watts [Required]

A number for the process load power in Watts.

• schedule [Required]

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

• fuel_type [Required]

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

• use_category

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

• radiant_fract

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

• latent_fract

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

• lost_fract

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

Outputs

• report

Reports, errors, warnings, etc.

• df_obj

The input Rooms with process loads assigned to them.

- [source code]

Apply an All-Air template HVAC to a list of Dragonfly Buildings, Stories or Room2Ds.

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

Inputs

• df_objs [Required]

  Dragonfly Buildings, Stories or Room2Ds to which the input template HVAC will be assigned. If a list of Room2Ds is input, all objects will receive the same HVAC instance. Otherwise, each object gets its own instance (eg. each input Story will get its own HVAC). This can also be an etire dragonfly Model.

• system_type [Required]

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

• vintage

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

• name

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

• economizer

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

  • NoEconomizer

  • DifferentialDryBulb

  • DifferentialEnthalpy

  • DifferentialDryBulbAndEnthalpy

  • FixedDryBulb

  • FixedEnthalpy

  • ElectronicEnthalpy

• sensible_hr

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

• latent_hr

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

• dcv

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

Outputs

• report

  Script variable OSHVACSystems

• df_objs

  The input Dragonfly objects with an all-air HVAC system applied.

- [source code]

Apply a customized IdealAirSystem to Dragonfly Buildings, Stories or Room2Ds.

Inputs

• df_objs [Required]

Dragonfly Buildings, Stories or Room2Ds to which the input ideal air properties will be assigned. This can also be an etire dragonfly Model.

• economizer

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

* NoEconomizer

* DifferentialDryBulb

* DifferentialEnthalpy

• dcv

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

• sensible_hr

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

• latent_hr

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

• heat_temp

A number for the maximum heating supply air temperature [C]. Default: 50, which is typical for many air-based HVAC systems.

• cool_temp

A number for the minimum cooling supply air temperature [C]. Default: 13, which is typical for many air-based HVAC systems.

• heat_limit

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

• cool_limit

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

• heat_avail

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

• cool_avail

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

Outputs

• report

The execution information, as output and error streams

• df_objs

The input Dragonfly object with the custom Ideal Air System assigned.

- [source code]

Apply a detailed Ironbug HVAC to Dragonfly Buildings, Stories or Room2Ds.

Inputs

• df_objs [Required]

Dragonfly Buildings, Stories or Room2Ds to which the input Ironbug HVAC will be assigned. This can also be an etire dragonfly Model. Only the relevant Room2Ds referenced in the _hvac_system will be assigned the HVAC system.

• hvac_system [Required]

A fully-detailed Irongbug HVAC system to be assigned to the input dragonfly objects.

• name

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

Outputs

• report

Reports, errors, warnings, etc.

• df_objs

The input Rooms or Model with the detailed HVAC system applied.

-

Create an OpenDSS Electrical Connector from linear geometry and power line properties, which include the wires and their geometrical arrangement.

Inputs

• geo [Required]

A line or polyline representing an Electrical Connector.

• power_line [Required]

Text for the ID of a PowerLine carried along the electrical connector, which will be looked up in the Power Lines library (the output from the "DF OpenDSS Libraries" component). This can also be a custom PowerLine object created using the Ladybug Tools SDK.

• name

Text to set the base name for the Electrical Connector, which will also be incorporated into unique ElectricalConnector identifier. If the name is not provided, a random one will be assigned.

Outputs

• connector

A Dragonfly Electrical Connector object that can be used within an Electrical Network.

-

Apply a template Service Hot Water (SHW) system to Dragonfly Buildings, Stories or Room2Ds.

Inputs

• df_objs [Required]

Dragonfly Buildings, Stories or Room2Ds to which the input template system will be assigned. This can also be a Honeybee Model for which all Rooms will be assigned the SHW system.

• system_type [Required]

Text for the specific type of service hot water system and equipment. The "HB SHW Templates" component has a full list of the supported system templates.

• name

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

• efficiency

A number for the efficiency of the heater within the system. For Gas systems, this is the efficiency of the burner. For HeatPump systems, this is the rated COP of the system. For electric systems, this should usually be set to 1. If unspecified this value will automatically be set based on the equipment_type. See below for the default value for each equipment type:

• condition

A number for the ambient temperature in which the hot water tank is located [C]. This can also be a Room2D in which the tank is located. (Default: 22).

• loss_coeff

A number for the loss of heat from the water heater tank to the surrounding ambient conditions [W/K]. (Default: 6 W/K).

Outputs

• report

Script variable OSHVACSystems

• df_objs

The input Rooms with a Service Hot Water system applied.

-

Apply a template system that only supplies heating and/or cooling (no ventilation) to a list of Dragonfly Buildings, Stories or Room2Ds.

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

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

Inputs

• df_objs [Required]

  Dragonfly Buildings, Stories or Room2Ds to which the input template HVAC will be assigned. If a list of Room2Ds is input, all objects will receive the same HVAC instance. Otherwise, each object gets its own instance (eg. each input Story will get its own HVAC). This can also be an etire dragonfly Model.

• system_type [Required]

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

• vintage

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

• name

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

Outputs

• report

  Script variable OSHVACSystems

• df_objs

  The input Dragonfly objects with a heating/cooling system applied.

-

Create a REopt ground-mounted photovoltaic system from its footprint geometry (horizontal Rhino surfaces).

Inputs

• geo [Required]

A horizontal Rhino surface (or closed polyline) representing a footprint to be converted into a ground-mounted photovoltaic system.

• name

Text to set the name for the PV system, which will also be incorporated into unique PV system identifier. If the name is not provided, a random one will be assigned.

• bldg

An optional Dragonfly Building with which the photovoltaic system is associated. If None, the PV system will be assumed to be a community PV field that isn't associated with a particular building meter.

Outputs

• ground_pv

A Dragonfly ground-mounted PV system object that can be exported to a GeoJSON in order to account for ground-mounted photovoltaics in a REopt simulation.

-

Create an OpenDSS Electrical Network, which represents all electrical infrastructure for an OpenDSS simulation.

This includes a substation, transformers, and all electrical connectors needed to connect these objects to Dragonfly Buildings.

Inputs

• substation [Required]

A Substation object representing the electrical substation supplying the network with electricity.

• transformers [Required]

An array of Transformer objects that are included within the electrical network. Generally, there should always be a transformer somewhere between the substation and a given building.

• connectors [Required]

An array of ElectricalConnector objects that are included within the electrical network. In order for a given connector to be valid within the network, each end of the connector must touch either another connector, a transformer/substation or a Dragonfly Building footprint. In order for the network as a whole to be valid, all Buildings and Transformers must be connected back to the Substation via connectors.

• name

Text to be used for the name and identifier of the Electrical Newtork. If no name is provided, it will be "unnamed".

Outputs

• report

Reports, errors, warnings, etc.

• network

A Dragonfly Electrical Newtork object possessing all electrical infrastructure for an OpenDSS simulation. This should be connected to the network_ input of the "DF Model to GeoJSON" component.

- [source code]

Deconstruct an OpenDSS Wire, PowerLine, or Transformer Properties into its constituient attributes and values.

Inputs

• dss_obj [Required]

An OpenDSS Wire, PowerLine, or Transformer Properties to be deconstructed. This can also be text for a Wire, PowerLine, or Transformer to be looked up in the library.

Outputs

• values

List of values for the attributes that define the OpenDSS object.

• attr_names

List of text that is the same length as the values, which notes the attribute name for each value.

- [source code]

Create an Ground Heat Exchanger Thermal Loop, which represents all infrastructure for a District Energy Simulation (DES) simulation.

This includes a ground heat exchanger and all thermal connectors needed to connect these objects to Dragonfly Buildings.

Inputs

• ghe_geo [Required]

Horizontal Rhino surfaces representing the footprints of ground heat exchangers. These ground heat exchanging fields contain the boreholes that supply the loop with thermal capacity. Multiple borehole fields can be located along the loop created by the _connector_geo.

• connector_geo [Required]

An array of lines or polylines representing the thermal connectors within the thermal loop. In order for a given connector to be valid within the loop, each end of the connector must touch either another connector, a building footprint, or a ground heat exchanger. In order for the loop as a whole to be valid, the connectors must form a single continuous loop when passed through the buildings and the heat exchanger field.

• clockwise

A boolean to note whether the direction of flow through the loop is clockwise (True) when viewed from above in the GeoJSON or it is counterclockwise (False). (Default: False).

• bore_depth

A number for the maximum depth of the heat-exchanging part of the boreholes in meters. This can also be a domain (aka interval) that sets the minimum and maximum depths of the boreholes (when the default minimum depth of 60 meters is not desirable). When the system demand cannot be met using boreholes with the minimum depth, the boreholes will be extended until either the loads or met or they reach the maximum depth specified here. So this typically represents the depth of bedrock or the point at which drilling deeper ceases to be practical. (Default: 135 meters).

• bore_spacing

A number for the minimum spacing between boreholes in meters. This can also be a domain (aka interval) that sets the minimum and maximum spacing of the boreholes (when the default maximum spacing of 10 meters is not desirable). When the system demand cannot be met using boreholes with the maximum spacing, the borehole spacing will be reduced until either the loads or met or they reach this minimum spacing. So this typically represents the spacing at which each borehole will interfere with neighboring ones so much that it is not worthwhile to decrease the spacing further. (Default: 3 meters).

• soil_conduct

A number for the soil conductivity in W/m-K. (Default: 2.3).

• soil_heat_cap

A number for the volumetric heat capacity of the soil in J/m3-K. (Default: 2,343,500).

• fluid_type

Text to indicate the type of fluid circulating through the ground heat exchanger loop. Choose from the options below. (Default: Water).

* Water

* EthylAlcohol

* EthyleneGlycol

* MethylAlcohol

* PropyleneGlycol

• concentration

A number between 0 and 60 for the concentration of the fluid_type in water in percent. Note that this variable has no effect when the fluid_type is Water. (Default: 35).

• name

Text to be used for the name and identifier of the Thermal Loop. If no name is provided, it will be "unnamed".

Outputs

• report

Reports, errors, warnings, etc.

• des_loop

A Dragonfly Thermal Loop object possessing all infrastructure for a District Energy Simulation (DES) simulation. This should be connected to the loop_ input of the "DF Model to GeoJSON" component.

- [source code]

Create an OpenDSS Substation from its footprint geometry (horizontal Rhino surfaces).

Inputs

• geo [Required]

  A horizontal Rhino surface representing a footprint to be converted into a Substation.

• name

  Text to set the name for the Substation, which will also be incorporated into unique Substation identifier. If the name is not provided, a random one will be assigned.

Outputs

• substation

  A Dragonfly Substation object that can be used within an Electrical Network.

- [source code]

Search for available TransformerProperties, PowerLines, and Wires within the dragonfly OpenDSS standards library (aka. the URBANopt extended cataolog).

Inputs

• keywords

Optional keywords to be used to narrow down the output list of objects. If nothing is input here, all available objects will be output.

• join_words

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

Outputs

• transformers

A list of all transformer properties within the dragonfly OpenDSS standards library (filtered by keywords_ if they are input).

• power_lines

A list of all power lines within the dragonfly OpenDSS standards library (filtered by keywords_ if they are input).

• wires

A list of all wires within the dragonfly OpenDSS standards library (filtered by keywords_ if they are input).

-

Create an RNM Road Network, which represents the streets along which electrical infrastructure will be placed by RNM.

This includes a substation and road geometries running between the buildings.

Inputs

• substation [Required]

A Substation object representing the electrical substation supplying the network with electricity.

• road_geo [Required]

An array of Lines or Polylines that represent the roads within the network.

• name

Text to be used for the name and identifier of the Road Newtork. If no name is provided, it will be "unnamed".

Outputs

• report

Reports, errors, warnings, etc.

• network

A Dragonfly Road Newtork object possessing all roads needed for an RNM simulation. This should be connected to the network_ input of the "DF Model to GeoJSON" component.

-

Customize the financial settings of a REopt analysis.

Inputs

• years

An integer for the number of years over which cost will be optimized. (Default: 25).

• escalation

A number between 0 and 1 for the escalation rate over the analysis. (Default: 0.023).

• tax

A number between 0 and 1 for the rate at which the owner/host of the system is taxed. (Default: 0.26).

• discount

A number between 0 and 1 for the discount rate for the owner/host of the system. (Default: 0.083).

• wind_cost

A number for the installation cost of wind power in US dollars per kW. (Default: 3013).

• pv_cost

A number for the installation cost of photovoltaic power in US dollars per kW. (Default: 1600).

• pv_grnd_cost

A number for the installation cost of photovoltaic power in US dollars per kW. (Default: 2200).

• storage_cost

A number for the installation cost of power storage in US dollars per kW. (Default: 840).

• gener_cost

A number for the installation cost of generators in US dollars per kW. (Default: 500).

Outputs

• financial_par

A REoptParameter object that can be plugged into the 'DF Run REopt' component.

-

Parse any CSV file output from an OpenDSS simulation.

Inputs

• dss_csv [Required]

  The file path of any CSV result file that has been generated from an OpenDSS simulation. This can be either a Building CSV with voltage information or transformers/connectors with loading information.

Outputs

• factors

  A list of data collections containing the dimensionless fractional values from the CSV results. For buildings, these represent the voltage at a given timestep divided by the standard outlet voltage (120 V). For transformers and connectors, these represent the power along the wire or transformer divided by the kVA rating of the object.

• condition

  A list of data collections noting the condition of a given object. For example, whether the object is over or under voltage (in the case of a building) or whether it is overloaded (in the case of a transformer or electrical connector).

- [source code]

Create an OpenDSS Transformer from its footprint geometry (horizontal Rhino surfaces).

Inputs

• geo [Required]

  A horizontal Rhino surface representing a footprint to be converted into a Transformer.

• properties [Required]

  Text for the properties of the Transformer to be looked up in the TransformerProperties library (the output from the "DF OpenDSS Libraries" component). This can also be a custom TransformerProperties object.

• name

  Text to set the base name for the Transformer, which will also be incorporated into unique Transformer identifier. If the name is not provided, a random one will be assigned.

Outputs

• transformer

  A Dragonfly Transformer object that can be used within an Electrical Network.

• Run Urban Weather Generator

• UWG Simulation Parameter

• Assign Building UWG Properties

• Assign Model UWG Properties

• Terrain

• Traffic Parameters

• Construct Design Day

• Create EPW

• Write DDY

• Write EPW

• Horizontal Infrared

• Import NOAA File

• Boundary Layer Parameters

• Luminous Efficacy

• Reference EPW Parameters

• Vegetation Parameters

-

Create a simulation parameter object that carries a complete set of Urban Weather Genreator (UWG) simulation settings and can be plugged into the "DF Run Urban Weather Generator" component.

Inputs

• run_period

A Ladybug Analysis Period object to describe the time period over which to run the simulation. If None, the simulation will be run for the whole year.

• timestep

An integer for the number of timesteps per hour at which the calculation will be run. (Default: 12).

• veg_par

A VegetationParameter object to specify the behavior of vegetation in the urban area. If None, generic vegetation parameters will be generated.

• epw_site

A ReferenceEPWSite object to specify the properties of the reference site where the input rural EPW was recorded. If None, generic airport properties will be generated.

• bnd_layer

A BoundaryLayerParameter to specify the properties of the urban boundary layer. If None, generic boundary layer parameters will be generated.

Outputs

• sim_par

A UWG SimulationParameter object that can be connected to the "DF Run Urban Weather Generator" component in order to specify UWG simulation settings

-

Run a an URBANopt geoJSON and scenario through Modelica Distric Energy System (DES) simulation.

The geoJSON must have a valid DES Loop assigned to it in order to run correctly through Modelica DES simulation.

Inputs

• geojson [Required]

The path to an URBANopt-compatible geoJSON file. This geoJSON file can be obtained form the "DF Model to geoJSON" component. The geoJSON must have a valid District Energy System (DES) Loop assigned to it in order to run correctly through the DES simulation.

• scenario [Required]

The path to an URBANopt .csv file for the scenario. This CSV file can be obtained form the "DF Run URBANopt" component.

• write [Required]

Set to "True" to run the component, install any missing dependencies, and write the Modelica files for the Distric Energy System.

• run

Set to "True" to translate the Modelica files to a Functional Mockup Unit (FMU) and then simulate the FMU. This will ensure that all result files appear in their respective outputs from this component.

Outputs

• report

Reports, errors, warnings, etc.

• sys_param

A JSON file containing all of the specifications of the District Energy System, including the detailed Building load profiles.

• modelica

A folder where all of the Modelica files of the District Energy System (DES) are written.

• results

A folder containing the results of the Modelica simulation if run_ is True and the simulation is successful.

-

Edit the properties of a Dragonfly Building that affect simulation with to the Urban Weather Generator (UWG).

Inputs

• building [Required]

  A Dragonfly Building which is to have its Urban Weather Generator (UWG) properties assigned.

• program

  Text for the name of the building program. Must be one of the options below. (Default: LargeOffice).

  • LargeOffice

  • MediumOffice

  • SmallOffice

  • MidriseApartment

  • Retail

  • StripMall

  • PrimarySchool

  • SecondarySchool

  • SmallHotel

  • LargeHotel

  • Hospital

  • Outpatient

  • Warehouse

  • SuperMarket

  • FullServiceRestaurant

  • QuickServiceRestaurant

• vintage

  Text for the vintage of the building. This will be used to set default constructions. Must be one of the options below or one of the options from the "HB Building Vintages" component, which will be mapped to one of the options below. (Default: New).

  • New

  • 1980_Present

  • Pre1980

• fr_canyon

  A number from 0 to 1 that represents the fraction of the building's waste heat from air conditioning that gets rejected into the urban canyon. (Default: 0.5).

• shgc

  A number from 0 to 1 that represents the SHGC of the building's windows. This is used to evaluate the amount of solar heat reflected into the street canyon. By default, it will be set by the building vintage and the Model climate zone.

• wall_alb

  A number from 0 to 1 that represents the exterior wall albedo of the building. By default, it will be set by the building program and the DoE commercial reference buildings.

• roof_alb

  A number from 0 to 1 that represents the exterior roof albedo of the building. By default, it will be set by the vintage, meaning 0.7 for New and 0.2 for 1980_Present and Pre1980.

• roof_veg

  A number from 0 to 1 that represents the fraction of the building's roofs covered in vegetation. (Default: 0).

Outputs

• report

  ...

• building

  The input Dragonfly Building with its UWG properties re-assigned based on the input.

-

Create an Fourth Generation Thermal Loop, which represents all infrastructure for a District Energy Simulation (DES) simulation.

This includes a central hot and chilled water plant for the district.

Inputs

• chilled_temp

A number for the temperature of chilled water in the DES in degrees Celsius. (Default: 6).

• hot_temp

A number for the temperature of hot water in the DES in degrees Celsius. (Default: 54).

• name

Text to be used for the name and identifier of the Thermal Loop. If no name is provided, it will be "unnamed".

Outputs

• report

Reports, errors, warnings, etc.

• des_loop

A Dragonfly Thermal Loop object possessing all infrastructure for a District Energy Simulation (DES) simulation. This should be connected to the loop_ input of the "DF Model to GeoJSON" component.

- [source code]

Morph a rural or airport EPW to reflect the conditions within an urban street canyon. The properties of this urban street canyon are specified in the connected _model.

For definitions of the inputs of the Urban Weather Generator, please see the UWG schema documentation (https://www.ladybug.tools/uwg-schema/index.html).

For a full list of publications on the Urban Weather Generator, see the MIT Urban Microclimate Group (http://urbanmicroclimate.scripts.mit.edu/publications.php).

Inputs

• model [Required]

  A Dragonfly Model to be used to morph the EPW for the urban area.

• epw_file [Required]

  Full path to an .epw file. This is the rural or airport file that will be morphed to reflect the climate conditions within an urban canyon.

• sim_par

  A dragonfly UWG SimulationParameter object that describes all of the setting for the simulation. If None, some default simulation parameters will be used.

• folder

  File path for the directory into which the the uwg JSON and morphed urban EPW will be written. If None, it will be written into the ladybug default_epw_folder within a subfolder bearing the name of the dragonfly Model.

• write [Required]

  Set to "True" to generate a UWG JSON from the connected _model and parameters. This JSON can be edited and simulated by the UWG directly.

• run

  Set to "True" to simulate the uwg_json with the Urban Weather Generator (UWG) and morph the input EPW to account for urban heat island. This can also be the integer "2", which will run the UWG silently (without any batch windows).

Outputs

• report

  Reports, errors, warnings, etc.

• uwg_json

  Path to a fully-simulatable JSON file following the UWG schema. This contains all of the relevant Dragonfly Model properties and input parameters.

• urban_epw

  Path to the morphed EPW file output from the UWG, which represents urban heat island conditions within the street canyon.

-

Construct a design day from a set of parameters.

Inputs

• name [Required]

  The name of the DesignDay object.

• day_type [Required]

  Text indicating the type of design day (ie. 'SummerDesignDay', 'WinterDesignDay' or other EnergyPlus days).

• location [Required]

  A Ladybug Location object describing the location of the design day.

• date [Required]

  A Ladybug Date for the day of the year on which the design day occurs. This should be in the format of 'DD Month' (eg. '1 Jan', '4 Jul'). The LB Calculate HOY component can also be used to construct this date.

• dry_bulb_max [Required]

  Maximum dry bulb temperature over the design day (in C).

• dry_bulb_range

  Dry bulb range over the design day (in C).

• humidity_type [Required]

  Type of humidity to use. (ie. Wetbulb, Dewpoint, HumidityRatio, Enthalpy)

• humidity_value [Required]

  The value of the humidity condition above.

• barometric_p

  Barometric pressure in Pa.

• wind_speed [Required]

  Wind speed over the design day in m/s.

• wind_dir [Required]

  Wind direction over the design day in degrees.

• sky_type [Required]

  Type of solar model to use. (eg. ASHRAEClearSky, ASHRAETau)

• sky_properties [Required]

  A list of properties describing the sky above. For ASHRAEClearSky this is a single value for clearness. For ASHRAETau, this is the tau_beam and tau_diffuse.

Outputs

• design_day

  Script output design_day.

-

Create a custom EPW object from a location and data collections of annual hourly data.

Inputs

• location [Required]

  A location object for the epw_file.

• dry_bulb_temp

  Annual hourly data collection for dry bulb temperature [C]

• dew_point_temp

  Annual hourly data collection for dew point temperature [C]

• wind_speed

  Annual hourly data collection for wind speed [m/s]

• wind_direction

  Annual hourly data collection for wind direction [degrees]

• direct_normal_rad

  Annual hourly data collection for direct normal radiation [Wh/m2] or [W/m2]

• diffuse_horiz_rad

  Annual hourly data collection for diffuse horizontal radiation [Wh/m2] or [W/m2]

• horiz_infrared_rad

  Annual hourly data collection for horizontal infrared radiation intensity [Wh/m2] or [W/m2]

• direct_normal_ill

  Annual hourly data collection for direct normal illuminance [lux]

• diffuse_horiz_ill

  Annual hourly data collection for diffuse horizontal illuminance [lux]

• total_sky_cover

  Annual hourly data collection for the fraction for total sky cover [tenths]

• atmos_pressure

  Annual hourly data collection for weather station pressure [Pa]

• visibility

  Annual hourly data collection for visibility [km]

• ceiling_height

  Annual hourly data collection for cloud ceiling height [m]

• model_year

  Annual hourly data collection for the year from which the hourly data has been extracted. This input is necessary when the input data collections are from a leap year.

• base_epw

  File path to an optional .epw to fill empty slots for data that has not been connected here.

• run [Required]

  Set to True to run the component and create the epw_obj.

Outputs

• report

  Reports, errors, warnings, etc.

• epw_obj

  An EPW object that can be written to a file using the Write EPW component.

-

Define the window opening properties for all apertures of a Dragonfly Building, Story, Room2D or Model.

Inputs

• df_objs [Required]

Dragonfly Buildings, Stories or Room2Ds to which window ventilation opening properties will be assigned. Note that this component assigns such properties to all Outdoor Apertures on the rooms. This can also be an entire Dragonfly Model.

• vent_cntrl [Required]

A Ventilation Control object from the "HB Ventilation Control" component, which dictates the opening behaviour of the Room's apertures.

• fract_area_oper

A number between 0.0 and 1.0 for the fraction of the window area that is operable. (Default: 0.5, typical of sliding windows).

• fract_height_oper

A number between 0.0 and 1.0 for the fraction of the distance from the bottom of the window to the top that is operable. (Default: 1.0, typical of windows that slide horizontally).

• discharge_coeff

A number between 0.0 and 1.0 that will be multipled by the area of the window in the stack (buoyancy-driven) part of the equation to account for additional friction from window geometry, insect screens, etc. (Default: 0.45, for unobstructed windows with insect screens). This value should be lowered if windows are of an awning or casement type and not allowed to fully open. Some common values for this coefficient include the following.

• wind_cross_vent

Boolean to indicate if there is an opening of roughly equal area on the opposite side of the Room such that wind-driven cross ventilation will be induced. If False, the assumption is that the operable area is primarily on one side of the Room and there is no wind-driven ventilation. (Default: False)

Outputs

• report

...

• df_objs

The input Dragonfly object with their window-opening properties edited.

-

Create a Terrain object representing the land on which an urban area sits.

This includes both the geometry and the properties of the pavement within the urban area.

Inputs

• terrain_geo [Required]

  An array of Breps or meshes that together represent the terrian. This should include the entire area of the site, including that beneath building footprints.

• albedo

  A number between 0 and 1 that represents the albedo (reflectivity) of the pavement. (Default: 0.1, typical of fresh asphalt).

• thickness

  A number that represents the thickness of the pavement material in meters. (Default: 0.5 meters).

• conductivity

  A number representing the conductivity of the pavement material in W/m-K. (Default: 1 W/m-K, typical of asphalt).

• vol_heat_cap

  A number representing the volumetric heat capacity of the pavement material in J/m3-K. This is the number of joules needed to raise one cubic meter of the material by 1 degree Kelvin. (Default: 1.6e6 J/m3-K, typical of asphalt).

Outputs

• terrain

  A Terrain object that can be plugged into the "DF Assign Model UWG Properties" component to specify the terrain of an urban area.

-

Create TrafficParameters representing the traffic within an urban area.

Inputs

• watts_per_area [Required]

  A number representing the maximum sensible anthropogenic heat flux of the urban area in watts per square meter. This is specifcally the heat that DOES NOT originate from buildings and mostly includes heat from automobiles, street lighting, and human metabolism. If autocalculate, it will be estimated frm the average building story count of the model hosting the traffic parameters (Default: autocalculate). Values for different cities can be found in (Sailor, 2011)[1]. Typical values include:

  • 20 W/m2 = A typical downtown area

  • 10 W/m2 = A commercial area in Singapore

  • 8 W/m2 = A typical mixed use part of Toulouse, France

  • 4 W/m2 = A residential area in Singapore

• weekday_sch

  A list of 24 fractional values that will be multiplied by the watts_per_area to produce hourly values for heat on the weekday of the simulation. (Default: a typical schedule for a commercial area).

• saturday_sch

  A list of 24 fractional values that will be multiplied by the watts_per_area to produce hourly values for heat on the Saturday of the simulation. (Default: a typical schedule for a commercial area).

• sunday_sch

  A list of 24 fractional values that will be multiplied by the watts_per_area to produce hourly values for heat on the Sunday of the simulation. (Default: a typical schedule for a commercial area).

Outputs

• traffic

  Traffic parameters that can be plugged into the "DF Assign Model UWG Properties" component to specify the behavior of traffic within an urban area.

-

Edit the properties of a Dragonfly Model that affect simulation with to the Urban Weather Generator (UWG).

Inputs

• model [Required]

  A Dragonfly Model which is to have its Urban Weather Generator (UWG) properties assigned.

• terrain

  A Terrain object that dictates the properties of the street and ground beneath the buildings. If None, a default terrain object will be generated by analysing all of the buildings in the Model and drawing a bounding rectangle in the XY plane around them.

• traffic

  A TrafficPararameter object that defines the activity and intensity of traffic within the urban street canyons. If None, traffic intensity will be approximated using the average building story count along with a generic traffic schedule.

• tree_cover

  A number from 0 to 1 that defines the fraction of the exposed terrain covered by trees. If None, it will be determined by evaluating the horizontal area of all ContextShade geometry that has a true is_vegetation property.

• grass_cover

  A number from 0 to 1 that defines the fraction of the exposed terrain that is covered by grass or shrubs. If None, no grass will be assumed for the urban area.

Outputs

• report

  ...

• model

  The input Dragonfly Model with its UWG properties re-assigned based on the input.

- [source code]

Calculate downwelling horizontal infrared radiation intensity from sky cover, dry bulb temperature, and dew point temperature.

Inputs

• sky_cover [Required]

  A value or data collection representing sky cover [tenths]

• dry_bulb [Required]

  A value or data collection representing dry bulb temperature [C]

• dew_point [Required]

  A value or data collection representing dew point temperature [C]

Outputs

• horiz_infrared

  A data collection or value indicating the downwelling horizontal infrared radiation [W/m2]

- [source code]

Import climate data from a .csv file of annual data obtained from the National Oceanic and Atmospheric Administration (NOAA) database. The database can be accessed here: https://gis.ncdc.noaa.gov/maps/ncei/cdo/hourly

Inputs

• noaa_file [Required]

  The path to a .csv file of annual data obtained from the NOAA database on your system as a string.

• time_zone

  Optional time zone for the station. If blank, a default time zone will be estimated from the longitude.

• timestep

  Integer forthe timestep at which the data collections should be output. Data in the .csv that does not conform to this timestep will be ignored in the output data collections. This can be set as high as 60 to ensure that all data from the .csv file is imported. However, such large data collections can be time consuming to edit. (Default: 1).

• run [Required]

  Set to True to run the component and import the data.