dragonfly package

Submodules

dragonfly.bldgtypes module

class dragonfly.bldgtypes.BuildingTypes[source]

Bases: object

Contains the accepted building typologies and contruction eras.

BLDG_PROGRAM = {'FullServiceRestaurant': 0, 'Hospital': 1, 'LargeHotel': 2, 'LargeOffice': 3, 'MedOffice': 4, 'MidRiseApartment': 5, 'OutPatient': 6, 'PrimarySchool': 7, 'QuickServiceRestaurant': 8, 'SecondarySchool': 9, 'SmallHotel': 10, 'SmallOffice': 11, 'StandAloneRetail': 12, 'StripMall': 13, 'SuperMarket': 14, 'WareHouse': 15}
BLDG_PROGRAM_CONVERTER = {'0': 'LargeOffice', '1': 'StandAloneRetail', '10': 'SuperMarket', '11': 'FullServiceRestaurant', '12': 'QuickServiceRestaurant', '2': 'MidRiseApartment', '3': 'PrimarySchool', '4': 'SecondarySchool', '5': 'SmallHotel', '6': 'LargeHotel', '7': 'Hospital', '8': 'OutPatient', '9': 'Warehouse', 'FULL SERVICE RESTAURANT': 'FullServiceRestaurant', 'FULLSERVICERESTAURANT': 'FullServiceRestaurant', 'HOSPITAL': 'Hospital', 'LARGE HOTEL': 'LargeHotel', 'LARGE OFFICE': 'LargeOffice', 'LARGEHOTEL': 'LargeHotel', 'LARGEOFFICE': 'LargeOffice', 'MEDIUM OFFICE': 'MediumOffice', 'MEDIUMOFFICE': 'MediumOffice', 'MIDRISE APARTMENT': 'MidRiseApartment', 'MIDRISEAPARTMENT': 'MidRiseApartment', 'OUT PATIENT': 'OutPatient', 'OUTPATIENT': 'OutPatient', 'Office': 'LargeOffice', 'PRIMARY SCHOOL': 'PrimarySchool', 'PRIMARYSCHOOL': 'PrimarySchool', 'QUICK SERVICE RESTAURANT': 'QuickServiceRestaurant', 'QUICKSERVICERESTAURANT': 'QuickServiceRestaurant', 'Retail': 'StandAloneRetail', 'SECONDARY SCHOOL': 'SecondarySchool', 'SECONDARYSCHOOL': 'SecondarySchool', 'SMALL HOTEL': 'SmallHotel', 'SMALL OFFICE': 'SmallOffice', 'SMALLHOTEL': 'SmallHotel', 'SMALLOFFICE': 'SmallOffice', 'STANDALONE RETAIL': 'StandAloneRetail', 'STANDALONERETAIL': 'StandAloneRetail', 'STRIP MALL': 'StripMall', 'STRIPMALL': 'StripMall', 'SUPERMARKET': 'SuperMarket', 'WAREHOUSE': 'WareHouse'}
BUILT_ERA = {'1980sPresent': 1, 'NewConstruction': 2, 'Pre1980s': 0}
BUILT_ERA_CONVERTER = {'0': 'Pre1980s', '1': '1980sPresent', "1980's-Present": '1980sPresent', '1980SPRESENT': '1980sPresent', '2': 'NewConstruction', 'NEWCONSTRUCTION': 'NewConstruction', 'New Construction': 'NewConstruction', 'PRE1980S': 'Pre1980s', "Pre-1980's": 'Pre1980s'}
GLZ_RATIO = {'FullServiceRestaurant': 0.182, 'Hospital': 0.1461, 'LargeHotel': 0.2663, 'LargeOffice': 0.38, 'MedOffice': 0.33, 'MidRiseApartment': 0.1499, 'OutPatient': 0.1985, 'PrimarySchool': 0.35, 'QuickServiceRestaurant': 0.14, 'SecondarySchool': 0.34, 'SmallHotel': 0.1087, 'SmallOffice': 0.212, 'StandAloneRetail': 0.071, 'StripMall': 0.105, 'SuperMarket': 0.109, 'WareHouse': 0.0058}
UWG_BUILT_ERA = {'New': 'NewConstruction', 'Pre80': 'Pre1980s', 'Pst80': '1980sPresent'}
ZONE_CONVERTER = {'1': 0, '1A': 0, '1B': 0, '1C': 0, '2': 1, '2A': 1, '2B': 2, '2C': 1, '3': 3, '3A': 3, '3B': 5, '3B-CA': 4, '3C': 6, '4': 7, '4A': 7, '4B': 8, '4C': 9, '5': 10, '5A': 10, '5B': 11, '5C': 10, '6': 12, '6A': 12, '6B': 13, '6C': 12, '7': 14, '7A': 14, '7B': 14, '7C': 14, '8': 15, '8A': 15, '8B': 15, '8C': 15}
ZONE_TYPE = {0: '1A', 1: '2A', 2: '2B', 3: '3A', 4: '3B-CA', 5: '3B', 6: '3C', 7: '4A', 8: '4B', 9: '4C', 10: '5A', 11: '5B', 12: '6A', 13: '6B', 14: '7', 15: '8'}
classmethod check_cimate_zone(climate_zone)[source]
classmethod check_era(bldg_era)[source]
classmethod check_program(bldg_program)[source]
classmethod default_glazing_ratio(bldg_program)[source]
classmethod get_era_index(era)[source]
classmethod get_program_index(program)[source]
classmethod get_program_list()[source]
classmethod get_readable_zone(climate_zone)[source]
classmethod get_uwg_era_index(era)[source]

dragonfly.dfobject module

class dragonfly.dfobject.DFObject[source]

Bases: object

Base class for Dragonfly typology, district, terrain, and vegetation.

isDFObject

Return True.

class dragonfly.dfobject.DFParameter[source]

Bases: object

Base class for Dragonfly BuildingPar, TrafficPar, VegetationPar, etc.

isDFParameter

Return True.

dragonfly.district module

class dragonfly.district.District(building_typologies, site_area, climate_zone, tree_coverage_ratio=None, grass_coverage_ratio=None, traffic_parameters=None, vegetation_parameters=None, pavement_parameters=None, characteristic_length=None)[source]

Bases: dragonfly.dfobject.DFObject

Represents an urban district inclluding buildings, ground cover, and traffic.

Properties:
typologies site_area climate_zone tree_coverage_ratio grass_coverage_ratio traffic_parameters vegetation_parameters pavement_parameters characteristic_length average_bldg_height site_coverage_ratio facade_to_site_ratio bldg_type_ratios
ToString()[source]

Overwrite .NET ToString method.

average_bldg_height

Return the average height of the buildings in the district.

bldg_type_ratios

Get or set the building types and corresponding ratios as a dictionary.

Note that setting the typology ratios here completely overwrites the building_typologies currently associated with this district object.

bldg_types

Return a list of the building types in the district.

building_typologies

Return a list of building typology objects for the urban area.

characteristic_length

Return the caracteristic length of the district.

climate_zone

Get the ASHRAE climate zone, whisch sets building constructions.

facade_to_site_ratio

Return the facade to site ratio.

floor_height

Get the average floor height of the buildings in the typology.

fract_heat_to_canyon

The fraction of the building’s heat that is rejected to the urban canyon.

classmethod from_geo_params(average_bldg_height, site_coverage_ratio, facade_to_site_ratio, bldg_type_ratios, climate_zone, tree_coverage_ratio=None, grass_coverage_ratio=None, traffic_parameters=None, vegetation_parameters=None, pavement_parameters=None, characteristic_length=None)[source]

Initialize a District from a list of urban geometry parameters.

Parameters:
  • average_bldg_height – The average height of the buildings in meters.
  • site_coverage_ratio – A number between 0 and 1 that represents the fraction of the district terrain that the building footprints occupy. It describes how close the buildings are to one another in the district.
  • facade_to_site_ratio – A number that represents the ratio of vertical urban surface area [walls] to the total terrain area of the district. This value can be greater than 1.
  • bldg_type_ratios – A dictoinary with keys that represent the DoE commercial template building programs and building ages separated by a comma (eg. MidRiseApartment,1980sPresent). Under each key of the dictionary, there should be a single decimal number indicative of the fraction of the urban area’s floor area taken by the typology. The sum of all decimals in the dictionary should equal 1.
  • climate_zone – A text string representing the ASHRAE climate zone. (eg. 5A). This is used to set default constructions for the buildings in the district.
  • tree_coverage_ratio – An number from 0 to 1 that defines the fraction of the urban area (including both pavement and roofs) that is covered by trees. The default is set to 0.
  • grass_coverage_ratio – An number from 0 to 1 that defines the fraction of the urban area (including both pavement and roofs) that is covered by grass/vegetation. The default is set to 0.
  • traffic_parameters – A dragonfly TrafficPar object that defines the traffic within an urban area.
  • vegetation_parameters – A dragonfly VegetationPar object that defines the behaviour of vegetation within an urban area.
  • pavement_parameters – A dragonfly PavementPar object that defines the makeup of pavement within the urban area.
  • characteristic_length – A number representing the linear dimension of the side of a square that encompasses the neighborhood in meters. The default is set to 500 m, which was found to be the recomendation for a typical mid-density urban area. Street, Michael A. (2013). Comparison of simplified models of urban climate for improved prediction of building energy use in cities. Thesis (S.M. in Building Technology)–Massachusetts Institute of Technology, Dept. of Architecture, http://hdl.handle.net/1721.1/82284
classmethod from_json(data)[source]

Create a district object from a dictionary :param data: {

building_typologies: list of Typology objects. site_area: float in square meters climate_zone: string tree_coverage_ratio: float between 0 and 1 grass_coverage_ratio: float between 0 and 1 traffic_parameters: traffic parameter dict vegetation_parameters: vegetation parameter dict pavement_parameters: pavement parameter dict characteristic_length: float
Parameters:} –
get_uwg_matrix()[source]

Return a matrix of bldg programs and construction eras needed by the uwg.

glz_ratio

Return the average glazing ratio of the buildings in the district.

grass_coverage_ratio

Get or set the fraction of the site area covered in grass.

isDistrict

Return True for District.

pavement_parameters

Get or set the pavement parameters of the district’s pavement.

roof_albedo

Return the average roof albedo of the district’s buildings.

roof_veg_fraction

Return the average roof vegetated fraction of the district’s buildings.

shgc

Get the solar heat gain coefficient of the district’s buildings.

site_area

Get or set the site area of the district.

site_coverage_ratio

Return the site coverage ratio of buildings to terrain.

to_json()[source]

Create a district dictionary Results:

{
building_typologies: list of Typology objects. site_area: float in square meters climate_zone: string tree_coverage_ratio: float between 0 and 1 grass_coverage_ratio: float between 0 and 1 traffic_parameters: traffic parameter dict vegetation_parameters: vegetation parameter dict pavement_parameters: pavement parameter dict characteristic_length: float

}

traffic_parameters

Get or set the traffic parameter of the district’s traffic.

tree_coverage_ratio

Get or set the fraction of the site area covered in trees.

vegetation_parameters

Get or set the vegetation parameters of the district’s vegetation.

wall_albedo

Return the average wall albedo of the district’s buildings.

dragonfly.terrain module

class dragonfly.terrain.Terrain(area, characteristic_length=None)[source]

Bases: dragonfly.dfobject.DFObject

Represents the terrain on which an urban area sits.

Properties:
area: The area of the urban terrain surface in square meters
(projected into the XY plane).
characteristic_length: A number representing the linear dimension

of the side of a square that encompasses the neighborhood in meters.

The default is set to 500 m, which was found to be the recomendation for a typical mid-density urban area. Street, Michael A. (2013). Comparison of simplified models of urban climate for improved prediction of building energy use in cities. Thesis (S.M. in Building Technology)–Massachusetts Institute of Technology, Dept. of Architecture, http://hdl.handle.net/1721.1/82284

ToString()[source]

Overwrite .NET ToString method.

area

Get or set the area of the terrain surface in the XY plane.

characteristic_length

Return the characteristic length.

classmethod from_geometry(terrainSrfs)[source]

Initialize a dragonfly terrain surface from a list of terrain breps :param terrainSrfs: A list of Rhino surfaces representing the terrian.

Returns:The dragonfly terrain object. surfaceBreps: The srfBreps representing the terrain
(projected into the XY plane).
Return type:terrain
classmethod from_json(data)[source]

Create a terrain object from a dictionary :param data: {

area: float characteristic_length: float
Parameters:} –
isTerrain

Return True for Terrain.

to_json()[source]

Create a terrain dictionary Results:

{
area: float characteristic_length: float

}

dragonfly.typology module

class dragonfly.typology.Typology(average_height, footprint_area, facade_area, bldg_program, bldg_era, floor_to_floor=None, floor_area=None, glz_ratio=None, uwg_parameters=None)[source]

Bases: dragonfly.dfobject.DFObject

Represents a group of buildings of the same typology in an urban area.

Properties:
average_height: The average height of the buildings of this typology
in meters.
footprint_area: The footprint area of the buildings of this typolog
in square meteres.
facade_area: The facade area of the buildings of this typology
in square meters.
bldg_program: A text string representing one of the 16 DOE building

program types to be used as a template for this typology. Choose from the following options:

FullServiceRestaurant Hospital LargeHotel LargeOffice MediumOffice MidRiseApartment OutPatient PrimarySchool QuickServiceRestaurant SecondarySchool SmallHotel SmallOffice StandAloneRetail StripMall SuperMarket Warehouse
bldg_era: A text string that sets the age of the buildings represented

by this typology. This is used to determine what constructions make up the walls, roofs, and windows based on international building codes over the last several decades. Choose from the following options:

Pre1980s 1980sPresent NewConstruction
floor_to_floor: A number that represents the average distance between
floors for the building typology. The default is set to 3.05 meters.
floor_area: A number that represents the floor area of the buiding in
square meteres. The default is auto-calculated using the footprint_area, average_height, and floor_to_floor.
glz_ratio: An optional number from 0 to 1 that represents the fraction
of the walls of the building typology that are glazed. If no value is input here, a default will be used that comes from the DoE building template from the bldg_program and bldg_era.
uwg_parameters: Optional UWG TypologyPar to set the properties of a
building typology that specifically relate to the UWG (ie. roof / wall albedo, fraction of bldg heat to canyon)
ToString()[source]

Overwrite .NET ToString method.

average_height

Get or set the average height of the buildings in meters.

bldg_era

Get or set the construction era of buildings in the typology.

bldg_program

Get or set the program of the buildings in the typology.

classmethod create_merged_typology(typ_one, typ_two)[source]

Creates a merged typology between two typologies of the same building type.

Parameters:
  • typ_one – The first Dragonfly building typology.
  • typ_two – The second Dragonfly building typology.
Returs:
merged_typology: A Dragonfly typology representing the
merged previous typologies.
facade_area

Get or set the facade area of the buildings in square meters.

floor_area

Get or set the interior floor area of the buildings in square meters.

floor_to_floor

Get or set the facade area of the buildings in square meters.

footprint_area

Get or set the footprint of the buildings in square meters.

classmethod from_footprint_geo_and_stories(bldg_footprint_breps, num_stories, bldg_program, bldg_era, floor_to_floor=None, glz_ratio=None, uwg_parameters=None)[source]

Initialize typology from building footprints and list of building stories.

Parameters:
  • bldg_footprint_breps – A list of surface rhino breps representing the building footprints of the typology.
  • num_stories – A list of integer values (all greater than or equal to 1) that represent the number of stories for each of the surfaces in the bldg_footprint_breps.
  • bldg_program – A text string representing one of the 16 DOE building program types to be used as a template for this typology.
  • bldg_era – A text string that sets the age of the buildings represented by this typology.
  • floor_to_floor – A number that represents the average distance between floors. Default is set to 3.05 meters.
  • glz_ratio – An optional number from 0 to 1 that represents the fraction of the walls of the building typology that are glazed. Default will come from the DoE building template from the bldg_program and bldg_era.
  • uwg_parameters – Optional UWG TypologyPar to set the properties of a building typology that specifically relate to the UWG (ie. roof / wall albedo, fraction of bldg heat to canyon)
Returns:

The dragonfly typology object perimeter_curves: The exterior-exposed curves of the footprints.
Return type:

typology
classmethod from_footprint_geometry(bldg_footprint_breps, avg_num_stories, bldg_program, bldg_era, floor_to_floor=None, glz_ratio=None, uwg_parameters=None)[source]

Initialize typology from building footprints and an average number of stories.

Parameters:
  • bldg_footprint_breps – A list of surface rhino breps representing the building footprints of the typology.
  • avg_num_stories – A float value (greater than or equal to 1) that represents the average number of stories of the buildings in the typology.
  • bldg_program – A text string representing one of the 16 DOE building program types to be used as a template for this typology.
  • bldg_era – A text string that sets the age of the buildings represented by this typology.
  • floor_to_floor – A number that represents the average distance between floors. Default is set to 3.05 meters.
  • glz_ratio – An optional number from 0 to 1 that represents the fraction of the walls of the building typology that are glazed. Default will come from the DoE building template from the bldg_program and bldg_era.
  • uwg_parameters – Optional UWG TypologyPar to set the properties of a building typology that specifically relate to the UWG (ie. roof / wall albedo, fraction of bldg heat to canyon)
Returns:

The dragonfly typology object perimeter_curves: The exterior-exposed curves of the footprints.
Return type:

typology
classmethod from_json(data)[source]

Create a typology object from a dictionary :param data: {

average_height: float footprint_area: float facade_area: float bldg_program: string bldg_era: string floor_to_floor: float floor_area: float glz_ratio: float between 0 and 1 uwg_parameters: uwg_parameters json
Parameters:} –
classmethod from_solid_geometry(bldg_breps, bldg_program, bldg_era, floor_to_floor=None, glz_ratio=None, uwg_parameters=None)[source]

Initialize a building typology from closed building brep geometry

Parameters:
  • bldg_breps – A list of closed rhino breps representing buildings of the typology.
  • bldg_program – A text string representing one of the 16 DOE building program types to be used as a template for this typology.
  • bldg_era – A text string that sets the age of the buildings represented by this typology.
  • floor_to_floor – A number that represents the average distance between floors. Default is set to 3.05 meters.
  • glz_ratio – An optional number from 0 to 1 that represents the fraction of the walls of the building typology that are glazed. Default will come from the DoE building template from the bldg_program and bldg_era.
  • uwg_parameters – Optional UWG TypologyPar to set the properties of a building typology that specifically relate to the UWG (ie. roof / wall albedo, fraction of bldg heat to canyon)
Returns:

The dragonfly typology object footprint_breps: Breps representing the footprints of the buildings. floor_breps: Breps representing the floors of the buildings in the typology. facade_breps: Breps representing the exposed facade surfaces of the typology.
Return type:

typology
glz_ratio

Get or set the glazing ratio of the buildings in the typology.

has_parent_district
isTypology

Return True for Typology.

number_of_stories

An integer representing the average number of stories of the buildings.

parent_district
to_json()[source]

Create a typology dictionary Results:

{
average_height: float footprint_area: float facade_area: float bldg_program: string bldg_era: string floor_to_floor: float floor_area: float glz_ratio: float between 0 and 1 uwg_parameters: uwg_parameters json

}

uwg_parameters

Get or set the uwg parameters (ie. wall/roof albedo, fract heat to canyon).

dragonfly.utilities module

A collection of auxiliary funtions for checking inputs.

dragonfly.utilities.fixRange(val, low, high)[source]
dragonfly.utilities.in_range(val, low, high, param_name='parameter')[source]

dragonfly.vegetation module

class dragonfly.vegetation.Vegetation(area, is_trees=False)[source]

Bases: dragonfly.dfobject.DFObject

Represents vegetation (either grass or trees) within an urban area.

Properties:
area: The area of the urban terrain covered by the vegetation in square meters
(projected into the XY plane).
is_trees: A boolean value that denotes whether the vegetation object represents
trees (True) or grass (False).
ToString()[source]

Overwrite .NET ToString method.

area

Get or set the area of the vegetation in the XY plane.

computeCoverage(terrain)[source]

Compute the coverage of the vegetation over a terrain surface.

Parameters:terrain – A dragonfly terrin object with which to compute coverage.
Returns:
A number between 0 and 1 representing the fraction of
the terrain covered by the vegetation.
Return type:coverage
classmethod from_geometry(veg_breps, is_trees=False)[source]

Initialize a dragonfly tree object from a list of closed tree breps

Parameters:
  • veg_breps – A list of closed Rhino breps representing the tree canopy.
  • is_trees – A boolean value that denotes whether the vegetation object represents trees (True) or grass (False).
Returns:

The dragonfly vegetation object. projected_breps: The veg_breps projected into the XY plane.
Return type:

vegetation
classmethod from_json(data)[source]

Create a vegetation object from a dictionary :param data: {

area: float is_trees: boolean
Parameters:} –
isVegetation

Return True for Vegetation.

is_trees

Get or set whether vegetation represents trees (True) or grass (False).

to_json()[source]

Create a vegetation dictionary Results:

{
area: float is_trees: boolean

}

Module contents