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:

• for modeling of district thermal systems

• for sizing transformers and electrical infrastructure

• for life cycle cost optimization of photovoltaics

• for estimation of urban heat island effects

Installation

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

Resources

Post your questions to and see the repository for source code.

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

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

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

- [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 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]

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.

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

- [source code]

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.

- [source code]

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.

- [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

- [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]

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]

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.

- [source code]

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.

- [source code]

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.

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

• Visualize All

• Visualize Floors

• Visualize Quick

- [source code]

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. This can also be a list of orphaned Honeybee Apertures and/or Doors to be added to the Dragonfly objects. In the case of Doors, they will be assigned to the Dragonfly object as such.

• project_dist

An optional number to be used to project the Aperture/Door geometry onto parent Faces. If specified, then sub-faces within this distance of the parent Face will be projected and added. Otherwise, Apertures/Doors will only be added if they are coplanar with a parent Face.

Outputs

• df_objs

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

- [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 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]

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.

- [source code]

Provides a list of dragonfly electrical network properties.

- [source code]

Add detailed skylight geometries to Dragonfly Room2Ds.

Inputs

• df_objs [Required]

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

• skylights [Required]

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

Outputs

• df_objs

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

-

Create Dragonfly ContextShade.

Inputs

-

Create a Dragonfly Story from individual Dragonfly Room2D objects.

Inputs

-

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

Inputs

-

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

-

Join small Room2Ds together within Dragonfly Stories.

This is particularly useful after operations like automatic core/perimeter offsetting, which can create several small Room2Ds from small segments in the outline boundary around the Story.

Inputs

-

Create a FluidParameter object that can be used to customize the fluid properties within a Ground Heat Exchanger (GHE) sizing simulation.

The output of this component can be used with either the "DF GHE Designer" component or the "DF GHE Thermal Loop" component.

Inputs

-

Create a PipeParameter object that can be used to customize the pipe properties within a Ground Heat Exchanger (GHE) sizing simulation.

The output of this component can be used with either the "DF GHE Designer" component or the "DF GHE Thermal Loop" component.

Inputs

-

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

Inputs

-

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

-

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.

-

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

Inputs

-

Create a HorizontalPipeParameter object that can be used to customize the properties of horizontal pipes contained within ThermalConnectors.

The output of this component can be used with the "DF GHE Thermal Loop" component.

Inputs

-

Create a BoreholeParameter object that can be used to customize the geometric constraints governing the boreholes of a GHE sizing simulation.

The output of this component can be used with either the "DF GHE Designer" component or the "DF GHE Thermal Loop" component.

Inputs

-

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

Inputs

-

Create a SoilParameter object that can be used to customize the soil and grout properties within a Ground Heat Exchanger (GHE) sizing simulation.

The output of this component can be used with either the "DF GHE Designer" component or the "DF GHE Thermal Loop" component.

Inputs

-

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

Inputs

-

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

-

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

-

Parse any CSV file output from an OpenDSS simulation.

Inputs

-

Provides a list of dragonfly Room2D properties.

-

Create an Fourth Generation Loop for a District Energy Simulation (DES) simulation.

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

Inputs

-

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

-

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

-

Create a GHEDesignParameter object that can be used to customize the criteria used to design a Ground Heat Exchanger (GHE).

The output of this component can be used with either the "DF GHE Designer" component or the "DF GHE Thermal Loop" component.

Inputs

-

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.

-

Run a Modelica District Energy System (DES) through an annual simulation using OpenModelica inside a Docker image (via Docker Desktop).

Docker Dekstop can be downloaded at the following link: https://www.docker.com/products/docker-desktop/

Inputs

-

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

Inputs

-

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

Inputs

-

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

-

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

-

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

-

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

Inputs

-

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

Inputs

-

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

-

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

Inputs

-

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

This includes basic properties like adjacency checks and all geometry checks. Furthermore, extension attributes for Energy and Radiance can be checked to ensure that the model can be simulated correctly in these engines.

Inputs

- [source code]

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]

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]

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]

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.

- [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 an Ground Heat Exchanger Loop 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).

• borehole

A GHE BoreholeParameter object from the "DF GHE Borehole Parameters" component, which customizes properties like borehole min/max depth and borehole min/max spacing.

• soil

A GHE SoilParameter object from the "DF GHE Soil Parameters" component. This can be used to customize the conductivity and density of the soil as well as the grout that fills the boreholes.

• fluid

A GHE Fluid object from the "DF GHE Fluid Parameters" component. This can be used to customize the fuild used (eg. water, glycol) as well as the concentration of the fluid. (Default: 100% Water).

• pipe

A GHE Pipe object from the "DF GHE Pipe Parameters" component. This can be used to customize the pipe diameter, conductivty, and roughness.

• horiz_pipe

A HorizontalPipe object to specify the properties of the horizontal pipes contained within ThermalConnectors. This can be used to customize the pipe insulation, pressure loss, etc.

• design

A GHEDesign object from the "DF GHE Design" component. This can be used to customize the mina and max entering fluid temperatures as well as the max boreholes.

• name

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

• ghe_names

An optional list of names that align with the input _ghe_geo and note the name to be used for each ground heat exchanger in the DES loop. If no names are provided, they will be derived from the DES Loop name above.

• connect_names

An optional list of names that align with the input _connector_geo and note the name to be used for each thermal connector in the DES loop. If no names are provided, they will be derived from the DES Loop name above.

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]

Load properties of the Ground Heat Exchangers (GHEs) from the "DF Write Modelica DES" component. This includes the positions of boreholes in each GHE, the G-function of each GHE that describes the response of the ground to load, an a range of other properties output from the sizing simulation performed by GHEDesigner.

Inputs

• sys_param [Required]

The system parameters JSON file output by the "DF Write Modelica DES" component. This includes the detailed Building load profiles, equipment specifications, and borehole field characteristics.

• des_loop [Required]

The GHE Thermal Loop object output by the "DF GHE Thermal Loop", which contains the geometry of the district energy system.

• ip

Boolean to note whether all outputs should be in SI or IP units. Setting this to True will result in all values in the report to IP and the month_temps will be in F instead of C. (Default: False).

Outputs

• report

Reports, errors, warnings, etc.

• boreholes

A list of points for the borehole locations within the _site.

• bore_geo

Script variable ColorNetAttr

• g_function

A data tree of G-function coefficients that describe the response of the ground to the input loads. Each pair of factors represents a point on the G-function. Flattening this data tree enables you to plug it directly into the "Ironbug Ground Heat Exchanger Vertical" component to simulate the ground heat exchanger in EnergyPlus.

• properties

A list of properties for the GHE that can be used to describe it in EnergyPlus simulations. The properties that can be plugged directly into the parameters of the "Ironbug Ground Heat Exchanger Vertical" component. The properties are in the following order:

• month_temps

A list of ground temperatures in Celsius with one value for each month of the period over which the GHEDesigner simulation was run (typically 20 years). This can be connected to a nativ Grasshopper "Quick Graph" component and used to check the drift in the ground temperature over long periods of time.

- [source code]

Assign cooling, heating and hot water loads to a Dragonfly Building to be used within a District Energy System (DES) simulation.

This component is intended specifically for the case that District Energy System (DES) simulation is to be performed without using URBANopt to generate building energy loads through EnergyPlus.

Inputs

• building [Required]

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

• cooling

An annual hourly data collection for building cooling loads for simulation with a DES. Note that this data collection must have a data type of Power.

• heating

An annual hourly data collection for building heating loads for simulation with a DES. Note that this data collection must have a data type of Power.

• hot_water

An annual hourly data collection for building service hot water loads for simulation with a DES. Note that this data collection must have a data type of Power.

Outputs

• building

The input Dragonfly Building with DES loads assigned to it. The Model created with this Building can be converted directly into a format that works with DES simulation using the "DF Model to DES" component without the need to run EnergyPlus simulations with the "DF Run URBANopt" component.

- [source code]

Use an URBANopt geoJSON with a Distric Energy System (DES) loop assigned to it along with the corresponding scenario (containing building loads) to generate a Modelica model of the district system.

The model is generated using the modules of the Modelica Buildings Library (MBL). More information on the MBL can be found here: https://simulationresearch.lbl.gov/modelica/

The Modelica model produced by this component can be opened and edited in any of the standard Modelica interfaces (eg. Dymola) or it can be simulated with OpenModelica inside a Docker image using the "DF Run Modelica" component.

Inputs

• geojson [Required]

The path to an URBANopt-compatible geoJSON file. This geoJSON file can be obtained form the "DF Model to geoJSON" component. Note that the geoJSON must have a valid District Energy System (DES) Loop assigned to it in order to run correctly with this 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.

• write [Required]

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

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, equipment specifications, borehole field characteristics (if applicable), etc.

• modelica

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

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

- [source code]

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.

• Run OpenDSS

• Run RNM

• Electrical Network

- [source code]

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]

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.

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

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.

- [source code]

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.

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

• all_3d_to_2d

Boolean to note whether 3D Rooms should be converted into the Room2D format even when this means some loss or simplification of geometry (True). If False (the default), only the Honeybee Rooms that meet the criteria for translation to Room2D without loss of geometry will be converted and the other 3D Rooms that don't meet this criteria will be stored under the Dragonfly Building.room_3ds property in their original Honeybee format. (Default: False).

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

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.

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

- [source code]

Set the ceiling plenum and/or floor plenum depth of rooms for any Dragonfly object (Room2Ds, Stories, Buildings, Model).

Inputs

• df_obj [Required]

A Dragonfly Model, Building, Story or Room2D to have plenum depths assigned to it.

• ceil_plenum

A number for the depth that ceiling plenums extend into rooms. Setting this to a positive value will result in a separate plenum room being split off of the Room2D volume during translation from Dragonfly to Honeybee.

• floor_plenum

A number for the depth that floor plenums extend into rooms. Setting this to a positive value will result in a separate plenum room being split off of the Room2D volume during translation from Dragonfly to Honeybee.

Outputs

• report

Reports, errors, warnings, etc.

• df_obj

The input Dragonfly object with ceiling or floor plenum depths set.

- [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]

Make the lowest unique Story(s) of a Building into basements.

This involves setting the outdoor walls of the basement stories to have ground boundary conditions and setting the is_ground_contact property on all relevant Room2Ds that are a basement or have a basement story below them.

Inputs

• building [Required]

A Dragonfly Building that will have some if its stories set to be basements. This can also be an entire Dragonfly Model in which case all Buildings in the model will have their basements set.

• bsmnt_count

A positive integer for the number of unique Stories on the Building to make into basements. (Default: 1).

• remove_win

Boolean to note whether basement Room2D segments with windows should have their outdoor boundary conditions and windows kept (True) or whether the windows should be removed in order to assign a ground boundary condition to all walls (False). (Default: False).

Outputs

• building

The input Dragonfly object with the wall boundary conditions changed.

- [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 (or DFJSON representing a full dragonfly Model) from which objects will be loaded into Grasshopper. This can also be the path to a Pollination Model Format (.POMF) file from which a dragonfly Model will be loaded. Note that, if the objects in the JSON are not a full model, they must be non-abridged in order to be loaded 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.

-

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

Inputs

-

Create a Dragonfly Model from a geoJSON file.

Inputs

-

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.

-

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

-

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

• Run REopt

• Run URBANopt

• Diversify Building Programs

- [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
• 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]

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

• no_plenum

Boolean to indicate whether ceiling/floor plenum depths assigned to Room2Ds should be ignored during translation. This results in each Room2D translating to a single Honeybee Room at the full floor-to-ceiling height instead of a base Room with (a) plenum Room(s). (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]

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.

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

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]

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]

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

• no_plenum

Boolean to indicate whether ceiling/floor plenum depths assigned to Room2Ds should be ignored during translation. This results in each Room2D translating to a single Honeybee Room at the full floor-to-ceiling height instead of a base Room with (a) plenum Room(s). (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