dragonfly.uwg package

Submodules

dragonfly.uwg.districtpar module

class dragonfly.uwg.districtpar.PavementPar(albedo=None, thickness=None, conductivity=None, volumetric_heat_capacity=None)

Bases: dragonfly.dfobject.DFParameter

Represents the makeup of pavement within the urban area.

Properties:

albedo: A number between 0 and 1 that represents the

surface albedo (or reflectivity) of the pavement. The default is set to 0.1, which is typical of fresh asphalt.

thickness: A number that represents the thickness of the

pavement material in meters (m). The default is set to 0.5 meters.

conductivity: A number representing the conductivity

of the pavement material in W/m-K. The default is set to 1 W/m-K, which is typical of asphalt.

volumetric_heat_capacity: A number representing the

volumetric heat capacity of the pavement material in J/m3-K. This is the number of joules needed to raise one cubic meter of the material by 1 degree Kelvin. The default is set to 1,600,000 J/m3-K, which is typical of asphalt.

ToString()

Overwrite .NET ToString method.

albedo

Get or set the road albedo.

conductivity

Get or set the road conductivity.

classmethod from_json(data)

Create a pavement parameter object from a dictionary :param data: {

albedo: float between 0 and 1 thickness: float positive conductivity: float positive volumetric_heat_capacity: float positive

Parameters:} –

isPavementPar

Return True for isPavementPar.

thickness

Get or set the road thickness.

to_json()

Create a pavement parameter dictionary Results:

{

albedo: float between 0 and 1 thickness: float positive conductivity: float positive volumetric_heat_capacity: float positive

}

volumetric_heat_capacity

Get or set the volumetric heat capacity.

class dragonfly.uwg.districtpar.TrafficPar(sensible_heat, weekday_schedule=[], saturday_schedule=[], sunday_schedule=[])

Bases: dragonfly.dfobject.DFParameter

Represents the traffic within an urban area.

Properties:

sensible_heat: A number representing the maximum sensible anthropogenic

heat flux of the urban area in watts per square meter.

weekday_schedule: A list of 24 fractional values that will be

multiplied by the sensible_heat to produce hourly values for heat on the weekday of the simulation. The default is a typical traffic schedule for a commerical area.

saturday_schedule: A list of 24 fractional values that will be

multiplied by the sensible_heat to produce hourly values for heat on the Saturday of the simulation. The default is a typical traffic schedule for a commerical area.

sunday_schedule: A list of 24 fractional values that will be

multiplied by the sensible_heat to produce hourly values for heat on the Sunday of the simulation. The default is a typical traffic schedule for a commerical area.

ToString()

Overwrite .NET ToString method.

classmethod from_json(data)

Create a traffic parameter object from a dictionary :param data: {

sensible_heat: float weekday_schedule: [] list of 24 fractional values saturday_schedule: [] list of 24 fractional values sunday_schedule: [] list of 24 fractional values

Parameters:} –

get_uwg_matrix()

A matrix of the traffic schedule that can be assigned to the uwg.

isTrafficPar

Return True for isTrafficPar.

saturday_avg_heat

Get the average W/m2 over the Saturday.

saturday_hourly_heat

Get a list of W/m2 on each hour of the Saturday.

saturday_schedule

Get or set the Saturday traffic schedule.

sensible_heat

Get or set the max sensible heat flux of the traffic.

sunday_avg_heat

Get the average W/m2 over the Sunday.

sunday_hourly_heat

Get a list of W/m2 on each hour of the Sunday.

sunday_schedule

Get or set the Sunday traffic schedule as a list.

to_json()

Create a traffic parameter dictionary :returns:

{

sensible_heat: float weekday_schedule: [] list of 24 fractional values saturday_schedule: [] list of 24 fractional values sunday_schedule: [] list of 24 fractional values

}

weekday_avg_heat

Get the average W/m2 over the Weekday.

weekday_hourly_heat

Get a list of W/m2 on each hour of the Weekday.

weekday_schedule

Get or set the Weekday traffic schedule.

class dragonfly.uwg.districtpar.VegetationPar(vegetation_albedo=0.25, vegetation_start_month=0, vegetation_end_month=0, tree_latent_fraction=0.7, grass_latent_fraction=0.5)

Bases: dragonfly.dfobject.DFParameter

Represents the behaviour of vegetation within an urban area.

Properties:

vegetation_albedo: A number between 0 and 1 that represents

the ratio of reflected radiation from vegetated surfaces to incident radiation upon them.

vegetation_start_month: An integer from 1 to 12 that represents

the month at which vegetation begins to affect the urban climate. The default is set to 0, which will automatically determine the vegetation start month by analyzing the epw to see which months have an average monthly temperature above 10 C.

vegetation_end_month: An integer from 1 to 12 that represents

the last month at which vegetation affect the urban climate. The default is set to 0, which will automatically determine the vegetation end month by analyzing the epw to see which months have an average monthly temperature above 10 C.

tree_latent_fraction: A number between 0 and 1 that represents

the the fraction of absorbed solar energy by trees that is given off as latent heat (evapotranspiration). Currently, this does not affect the moisture balance in the uwg but it will affect the temperature. If no value is input here, a typical value of 0.7 will be assumed.

grass_latent_fraction: A number between 0 and 1 that represents

the the fraction of absorbed solar energy by grass that is given off as latent heat (evapotranspiration). Currently, this does not affect the moisture balance in the uwg but it will affect the temperature. If no value is input here, a typical value of 0.5 will be assumed.

ToString()

Overwrite .NET ToString method.

classmethod from_json(data)

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

vegetation_albedo: float between 0 and 1 vegetation_start_month: int between 0 and 12 vegetation_end_month: int between 0 and 12 tree_latent_fraction: float between 0 and 1 grass_latent_fraction: float between 0 and 1

Parameters:} –

grass_latent_fraction

Return the grass latent fraction.

isVegetationPar

Return True for isVegetationPar.

to_json()

Create a vegetation parameter dictionary :returns:

{

vegetation_albedo: float between 0 and 1 vegetation_start_month: int between 0 and 11 vegetation_end_month: int between 0 and 11 tree_latent_fraction: float between 0 and 1 grass_latent_fraction: float between 0 and 1

}

tree_latent_fraction

Return the tree latent fraction.

veg_end_month_text

The text name of the vegetation end month.

veg_start_month_text

The text name of the vegetation start month.

vegetation_albedo

Get or set the vegetation albedo.

vegetation_end_month

Get or set the vegetation end month.

vegetation_start_month

Get or set the vegetation start month.

dragonfly.uwg.regionpar module

class dragonfly.uwg.regionpar.BoundaryLayerPar(day_boundary_layer_height=None, night_boundary_layer_height=None, inversion_height=None, circulation_coefficient=None, exchange_coefficient=None)

Bases: dragonfly.dfobject.DFParameter

Represents the properties of the urban boundary layer.

Properties:

day_boundary_layer_height: A number that represents the height

in meters of the urban boundary layer during the daytime. This is the height to which the urban meterorological conditions are stable and representative of the overall urban area. Typically, this boundary layer height increases with the height of the buildings. The default is set to 1000 meters.

night_boundary_layer_height: A number that represents the height

in meters of the urban boundary layer during the nighttime. This is the height to which the urban meterorological conditions are stable and representative of the overall urban area. Typically, this boundary layer height increases with the height of the buildings. The default is set to 80 meters.

inversion_height: A number that represents the height at which

the vertical profile of potential temperature becomes stable. It is the height at which the profile of air temperature becomes stable. Can be determined by flying helium balloons equipped with temperature sensors and recording the air temperatures at different heights. The default is set to 150 meters.

circulation_coefficient: A number representing the circulation coefficient.

The default is 1.2 per Bueno, Bruno (2012).

exchange_coefficient: A number representing the exchange coefficient.

The default is 1.0 per Bueno, Bruno (2014).

ToString()

Overwrite .NET ToString method.

circulation_coefficient

Get or set the circulation coefficient.

day_boundary_layer_height

Get or set the daytime boundary layer height.

exchange_coefficient

Get or set the exchange coefficient.

classmethod from_json(data)

Create a boundary layer parameter object from a dictionary :param data: {

day_boundary_layer_height: float positive night_boundary_layer_height: float positive inversion_height: float positive circulation_coefficient: float positive exchange_coefficient: float positive

Parameters:} –

inversion_height

Get or set the inversion height.

isBoundaryLayerPar

Return True for isBoundaryLayerPar.

night_boundary_layer_height

Get or set the nighttime boundary layer height.

to_json()

Create a boundary layer parameter dictionary Results:

{

day_boundary_layer_height: float positive night_boundary_layer_height: float positive inversion_height: float positive circulation_coefficient: float positive exchange_coefficient: float positive

}

class dragonfly.uwg.regionpar.RefEPWSitePar(average_obstacle_height=None, vegetation_coverage=None, temp_measure_height=None, wind_measure_height=None)

Bases: dragonfly.dfobject.DFParameter

Represents properties of the reference site where the original EPW was recorded.

Properties:

average_obstacle_height: A number that represents the height in

meters of objects that obstruct the view to the sky at the weather station site. This includes both trees and buildings. The default is set to 0.1 meters.

vegetation_coverage: A number between 0 and 1 that represents

that fraction of the reference EPW site that is covered in grass. If nothing is input here, a defailt of 0.9 will be used.

temp_measure_height: A number that represents the height in meters

at which temperature is measured on the weather station. The default is set to 10 meters as this is the standard measurement height for US Department of Energy EPW files.

wind_measure_height: A number that represents the height in meters

at which wind speed is measured on the weather station. The default is set to 10 meters as this is the standard measurement height for US Department of Energy EPW files.

ToString()

Overwrite .NET ToString method.

average_obstacle_height

Get or set the average obstacle height.

classmethod from_json(data)

Create a reference epw parameter object from a dictionary :param data: {

average_obstacle_height: float vegetation_coverage: float between 0 and 1 temp_measure_height: float between 0 and 1 wind_measure_height: float

Parameters:} –

isRefEPWSitePar

Return True for isRefEPWSitePar.

temp_measure_height

Get or set the temperature measurement height.

to_json()

Create a reference epw parameter dictionary Results:

{

average_obstacle_height: float vegetation_coverage: float between 0 and 1 temp_measure_height: float between 0 and 1 wind_measure_height: float

}

vegetation_coverage

Get or set the vegetation coverage.

wind_measure_height

Get or set the wind measurement height.

dragonfly.uwg.run module

class dragonfly.uwg.run.RunManager(epw_file, district, epw_site_par=None, boundary_layer_par=None, analysis_period=None, sim_timestep=None)

Bases: object

Object to interface between dragonfly and the uwg.

Properties:

epw_file: An .epw file path on your system.

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

district: A dragonfly District object representing the urban area. epw_site_par: Optional dragonfly RefEPWSitePar object. boundary_layer_par: Optional dragonfly BoundaryLayerPar object. analysis_period: A ladybug AnalysisPeriod indicating the time period

of the epw_file to be morphed. The default is set to run the entire year

sim_timestep: The timestep at which the simulation is run in seconds.

The default is set to 300 seconds (5 minutes).

run()

Directly run the UWG to generate a morphed EPW. This method will only work if you have the uwg Python library installed.

save_uwg_file()

Save all of the properties of the RunManager to a .uwg file. These .uwg files can be parsed by the UWG engine.

ToString()

Overwrite .NET ToString method.

analysis_period

Get or set the AnalysisPeriod over which the simulation runs.

boundary_layer_par

Get or set the BoundaryLayerPar object.

district

Get or set the District object.

epw_file

Get or set the EPW file path

epw_site_par

Get or set the RefEPWSitePar object.

classmethod from_json(data)

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

epw_file: list of Typology objects district: dragonfly district disct epw_site_par: epw site parameter dict boundary_layer_par: boundary layer parameter dict analysis_period: ladybug analysis period dict sim_timestep: simulation timestep in seconds

Parameters:} –

run(urban_epw_path=None)

Run the UWG using the inputs to the RunManager.

Parameters:urban_epw_path – Full file path to the morphed epw. The default is set to go to an URBAN folder in the same directory as the existing rural EPW. Returns:The file path to the morphed epw. Return type:urban_epw_path

save_uwg_file(uwg_file_path=None)

Write the properties of the RunManager to a .uwg file.

Parameters:uwg_file_path – Full file path to the .uwg file that you want to write. The default is set to go to an URBAN folder in the same directory as the existing rural EPW. Returns:The file path to the .uwg file. Return type:uwg_file_path

sim_timestep

Get or set the simulation timestep in seconds.

to_json()

Create a UWG RunManager dictionary Results:

{

epw_file: list of Typology objects district: dragonfly district disct epw_site_par: epw site parameter dict boundary_layer_par: boundary layer parameter dict analysis_period: ladybug analysis period dict sim_timestep: simulation timestep in seconds

}

uwg_file_string

Return a string that can be written to a .uwg file.

dragonfly.uwg.typologypar module

class dragonfly.uwg.typologypar.TypologyDefaults

Bases: object

Contains default values from the DOE commercial building reference

ROOF_ALBEDO = {'1980sPresent': 0.2, 'NewConstruction': 0.7, 'Pre1980s': 0.2}

SHGC = {'1980sPresent': {0: 0.251, 1: 0.251, 2: 0.251, 3: 0.255, 4: 0.44, 5: 0.251, 6: 0.392, 7: 0.355, 8: 0.362, 9: 0.392, 10: 0.385, 11: 0.385, 12: 0.385, 13: 0.385, 14: 0.487}, 'NewConstruction': {0: 0.251, 1: 0.251, 2: 0.251, 3: 0.252, 4: 0.252, 5: 0.252, 6: 0.39, 7: 0.385, 8: 0.385, 9: 0.385, 10: 0.385, 11: 0.385, 12: 0.385, 13: 0.385, 14: 0.487}, 'Pre1980s': {0: 0.54, 1: 0.54, 2: 0.54, 3: 0.54, 4: 0.54, 5: 0.54, 6: 0.54, 7: 0.54, 8: 0.54, 9: 0.54, 10: 0.407, 11: 0.407, 12: 0.407, 13: 0.407, 14: 0.407}}

WALL_ALBEDO = {'FullServiceRestaurant': 0.15, 'Hospital': 0.08, 'LargeHotel': 0.08, 'LargeOffice': 0.08, 'MedOffice': 0.15, 'MidRiseApartment': 0.15, 'OutPatient': 0.15, 'PrimarySchool': 0.15, 'QuickServiceRestaurant': 0.22, 'SecondarySchool': 0.15, 'SmallHotel': 0.15, 'SmallOffice': 0.08, 'StandAloneRetail': 0.08, 'StripMall': 0.08, 'SuperMarket': 0.08, 'WareHouse': 0.08}

classmethod roof_albedo_by_era(built_era)

Default wall albedo based on built_era string.

classmethod shgc_by_era_zone(built_era, climate_zone)

Default solar heat coeff based on built_era string and climate_zone int.

classmethod wall_albedo_by_type(bldg_type)

Return default wall albedo based on bldg_type string.

class dragonfly.uwg.typologypar.TypologyPar(fract_heat_to_canyon=None, shgc=None, wall_albedo=None, roof_albedo=None, roof_veg_fraction=None)

Bases: dragonfly.dfobject.DFParameter

Represents the properties of a building typology that relate to the UWG.

Properties:

fract_heat_to_canyon: A number from 0 to 1 that represents the fraction

the building’s waste heat from air conditioning that gets rejected into the urban canyon. The default is set to 0.5.

shgc: A number from 0 to 1 that represents the SHGC of the

buildings in the typology.

wall_albedo: A number from 0 to 1 that represents the exterior

wall albedo of the buildings in the typology. The default is taken from the DOE commercial building reference and varies by building typology type.

roof_albedo: A number from 0 to 1 that represents the exterior

roof albedo of the buildings in the typology. The default is 0.7 for NewConstruction and 0.2 for Pre1980s and 1980sPresent.

roof_veg_fraction: A number from 0 to 1 that represents the

roof vegetation fraction of the buildings in the typology.

ToString()

Overwrite .NET ToString method.

fract_heat_to_canyon

Get or set the fraction of the bldg heat rejected to the urban canyon.

classmethod from_json(data)

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

fract_heat_to_canyon: float between 0 and 1 shgc: float wall_albedo: float between 0 and 1 roof_albedo: float between 0 and 1 roof_veg_fraction: float between 0 and 1

Parameters:} –

isTypologyPar

Return True for isTypologyPar.

roof_albedo

Get or set the exterior roof albedo of the buildings in the typology.

roof_veg_fraction

Get or set the roof vegetation fraction of the buildings in the typology.

shgc

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

to_json()

Create a typology parameter dictionary :returns:

{

fract_heat_to_canyon: float between 0 and 1 shgc: float wall_albedo: float between 0 and 1 roof_albedo: float between 0 and 1 roof_veg_fraction: float between 0 and 1

}

wall_albedo

Get or set the exterior wall albedo of the buildings in the typology.

Module contents

Dragonfly Urban Weather Generator Classes.