+[docs]
+classBuildingUWGProperties(object):
+"""UWG Properties for Dragonfly Building.
+
+ Args:
+ host: A dragonfly_core Building object that hosts these properties.
+ program: Text for the name of the building program. Must be one of the
+ options below. (Default: LargeOffice).
+
+ * LargeOffice
+ * MediumOffice
+ * SmallOffice
+ * MidriseApartment
+ * Retail
+ * StripMall
+ * PrimarySchool
+ * SecondarySchool
+ * SmallHotel
+ * LargeHotel
+ * Hospital
+ * Outpatient
+ * Warehouse
+ * SuperMarket
+ * FullServiceRestaurant
+ * QuickServiceRestaurant
+
+ vintage: Text for the vintage of the building. This will be used to set
+ default constructions. Must be one of the options below. (Default: New).
+
+ * New
+ * 1980_Present
+ * Pre1980
+
+ fract_heat_to_canyon: A number from 0 to 1 that represents the fraction of
+ the building's waste heat from air conditioning that gets rejected
+ into the urban canyon. (Default: 0.5).
+ shgc: A number from 0 to 1 that represents the SHGC of the building's windows.
+ Used to evaluate the amount of solar heat reflected into the street canyon.
+ If autocalculate, it will be set by the building vintage and the Model
+ climate zone. (Default: autocalculate).
+ wall_albedo: A number from 0 to 1 that represents the exterior wall albedo
+ of the building. If autocalculate, it will be set by the building program
+ and the DoE commercial reference buildings. (Default: autocalculate).
+ roof_albedo: A number from 0 to 1 that represents the exterior roof albedo of
+ the building. If autocalculate, it will be set by the vintage, meaning 0.7
+ for New and 0.2 for 1980_Present and Pre1980. (Default: autocalculate).
+ roof_veg_fraction: A number from 0 to 1 that represents the roof vegetation
+ fraction of the building. (Default: 0).
+
+ Properties:
+ * host
+ * program
+ * vintage
+ * fract_heat_to_canyon
+ * shgc
+ * wall_albedo
+ * roof_albedo
+ * roof_veg_fraction
+ """
+ __slots__=('_host','_program','_vintage','_fract_heat_to_canyon','_shgc',
+ '_wall_albedo','_roof_albedo','_roof_veg_fraction')
+
+ PROGRAMS= \
+ ('LargeOffice','MediumOffice','SmallOffice','MidriseApartment','Retail',
+ 'StripMall','PrimarySchool','SecondarySchool','SmallHotel','LargeHotel',
+ 'Hospital','Outpatient','Warehouse','SuperMarket',
+ 'FullServiceRestaurant','QuickServiceRestaurant')
+ VINTAGES=('New','1980_Present','Pre1980')
+ _VINTAGE_MAP={'New':'new','1980_Present':'pst80','Pre1980':'pre80'}
+
+ def__init__(self,host,program='LargeOffice',vintage='New',
+ fract_heat_to_canyon=0.5,shgc=autocalculate,wall_albedo=autocalculate,
+ roof_albedo=autocalculate,roof_veg_fraction=0):
+"""Initialize Building UWG properties."""
+ self._host=host
+ self.program=program
+ self.vintage=vintage
+ self.fract_heat_to_canyon=fract_heat_to_canyon
+ self.shgc=shgc
+ self.wall_albedo=wall_albedo
+ self.roof_albedo=roof_albedo
+ self.roof_veg_fraction=roof_veg_fraction
+
+ @property
+ defhost(self):
+"""Get the Building object hosting these properties."""
+ returnself._host
+
+ @property
+ defprogram(self):
+"""Get or set text for the name of the building program."""
+ returnself._program
+
+ @program.setter
+ defprogram(self,value):
+ assertvalueinself.PROGRAMS,'Program "{}" is not acceptable for the UWG. ' \
+ 'Choose from the following:\n{}'.format(value,'\n'.join(self.PROGRAMS))
+ self._program=value
+
+ @property
+ defprogram_uwg(self):
+"""Get text for the building program in a format that the UWG likes."""
+ ifself._program=='Retail':
+ return'standaloneretail'
+ elifself._program=='MediumOffice':
+ return'medoffice'
+ returnself._program.lower()
+
+ @property
+ defvintage(self):
+"""Get or set text for the vintage of the building."""
+ returnself._vintage
+
+ @vintage.setter
+ defvintage(self,value):
+ assertvalueinself.VINTAGES,'Vintage "{}" is not acceptable for the UWG. ' \
+ 'Choose from the following:\n{}'.format(value,'\n'.join(self.VINTAGES))
+ self._vintage=value
+
+ @property
+ defvintage_uwg(self):
+"""Get text for the building vintage in a format that the UWG likes."""
+ returnself._VINTAGE_MAP[self._vintage]
+
+ @property
+ deffract_heat_to_canyon(self):
+"""Get or set the fraction of the bldg heat rejected to the urban canyon."""
+ returnself._fract_heat_to_canyon
+
+ @fract_heat_to_canyon.setter
+ deffract_heat_to_canyon(self,value):
+ self._fract_heat_to_canyon=float_in_range(value,0,1,'fract_heat_to_canyon')
+
+ @property
+ defshgc(self):
+"""Get or set the SHGC of the building."""
+ returnself._shgcifself._shgcisnotNoneelseautocalculate
+
+ @shgc.setter
+ defshgc(self,value):
+ ifvalue==autocalculate:
+ self._shgc=None
+ else:
+ self._shgc=float_in_range(value,0,1,'shgc')
+
+ @property
+ defwall_albedo(self):
+"""Get or set the exterior wall albedo of the building."""
+ ifself._wall_albedoisNone:
+ return_RefDefaults.wall_albedo_by_type(self._program)
+ returnself._wall_albedo
+
+ @wall_albedo.setter
+ defwall_albedo(self,value):
+ ifvalue==autocalculate:
+ self._wall_albedo=None
+ else:
+ self._wall_albedo=float_in_range(value,0,1,'wall_albedo')
+
+ @property
+ defroof_albedo(self):
+"""Get or set the exterior roof albedo of the building."""
+ ifself._roof_albedoisNone:
+ return_RefDefaults.roof_albedo_by_era(self._vintage)
+ returnself._roof_albedo
+
+ @roof_albedo.setter
+ defroof_albedo(self,value):
+ ifvalue==autocalculate:
+ self._roof_albedo=None
+ else:
+ self._roof_albedo=float_in_range(value,0,1,'roof_albedo')
+
+ @property
+ defroof_veg_fraction(self):
+"""Get or set the roof vegetation fraction of the building."""
+ returnself._roof_veg_fraction
+
+ @roof_veg_fraction.setter
+ defroof_veg_fraction(self,value):
+ self._roof_veg_fraction=float_in_range(value,0,1,'roof_veg_fraction')
+
+
+[docs]
+ defdefault_shgc(self,climate_zone):
+"""Get the default DoE Reference Building SHGC for this building.
+
+ This is used whenever the building's shgc property is autocalculate.
+
+ Args:
+ climate_zone: Text for the ASHRAE climate zone, which must include
+ the humidity letter (eg. "4A") unless it is climate zone 7 or 8.
+ """
+ return_RefDefaults.shgc_by_era_zone(self._vintage,climate_zone)
+
+
+
+[docs]
+ definfer_program_from_energy_program(self):
+"""Attempt to infer the UWG building program from the honeybee-energy program.
+
+ The inferring will happen by first finding the most common energy ProgramType
+ among the assigned Room2Ds. If the identifier of this most common program
+ contains the name of an acceptable UWG building program, it will be assigned
+ as this object's building program. If no match is found or there's no
+ honeybee-energy extension installed, this object's program will remain unchanged.
+ """
+ try:
+ room_progs=[rm.properties.energy.program_type.identifier
+ forrminself.host.unique_room_2ds]
+ exceptAttributeError:# dragonfly-energy extension is not installed
+ room_progs=None
+ ifroom_progsisnotNone:
+ primary_prog=max(set(room_progs),key=room_progs.count)
+ forproginself.PROGRAMS:
+ ifproginprimary_prog:
+ self._program=prog
+ break
+
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data,host):
+"""Create BuildingUWGProperties from a dictionary.
+
+ Note that the dictionary must be a non-abridged version for this
+ classmethod to work.
+
+ Args:
+ data: A dictionary representation of BuildingUWGProperties.
+ host: A Building object that hosts these properties.
+ """
+ assertdata['type']=='BuildingUWGProperties', \
+ 'Expected BuildingUWGProperties. Got {}.'.format(data['type'])
+ prog,era,f_can,shgc,w_alb,r_alb,r_veg=cls._default_keys(data)
+ returncls(host,prog,era,f_can,shgc,w_alb,r_alb,r_veg)
+
+
+
+[docs]
+ defapply_properties_from_dict(self,abridged_data):
+"""Apply properties from a BuildingUWGPropertiesAbridged dictionary.
+
+ Args:
+ abridged_data: A BuildingUWGPropertiesAbridged dictionary (typically
+ coming from a Model).
+ """
+ prog,era,f_can,shgc,w_alb,r_alb,r_veg=self._default_keys(abridged_data)
+ self.program=prog
+ self.vintage=era
+ self.fract_heat_to_canyon=f_can
+ self.shgc=shgc
+ self.wall_albedo=w_alb
+ self.roof_albedo=r_alb
+ self.roof_veg_fraction=r_veg
+
+
+
+[docs]
+ defto_dict(self,abridged=False):
+"""Return Building UWG properties as a dictionary.
+
+ Args:
+ abridged: Boolean for whether the full dictionary of the Building should
+ be written (False) or just the identifier of the the individual
+ properties (True). Default: False.
+ """
+ base={'uwg':{}}
+ base['uwg']['type']='BuildingUWGProperties'ifnot \
+ abridgedelse'BuildingUWGPropertiesAbridged'
+
+ # write all of the required properties
+ base['uwg']['program']=self._program
+ base['uwg']['vintage']=self._vintage
+ base['uwg']['fract_heat_to_canyon']=self._fract_heat_to_canyon
+ base['uwg']['roof_veg_fraction']=self._roof_veg_fraction
+
+ # write all of the optional properties
+ ifself._shgcisnotNone:
+ base['uwg']['shgc']=self._shgc
+ ifself._wall_albedoisnotNone:
+ base['uwg']['wall_albedo']=self._wall_albedo
+ ifself._roof_albedoisnotNone:
+ base['uwg']['roof_albedo']=self._roof_albedo
+ returnbase
+[docs]
+ defduplicate(self,new_host=None):
+"""Get a copy of this object.
+
+ new_host: A new Building object that hosts these properties.
+ If None, the properties will be duplicated with the same host.
+ """
+ _host=new_hostorself._host
+ _new_obj=BuildingUWGProperties(
+ _host,self._program,self._vintage,self._fract_heat_to_canyon)
+ _new_obj._shgc=self._shgc
+ _new_obj._wall_albedo=self._wall_albedo
+ _new_obj._roof_albedo=self._roof_albedo
+ _new_obj._roof_veg_fraction=self._roof_veg_fraction
+ return_new_obj
+[docs]
+classContextShadeUWGProperties(object):
+"""UWG Properties for Dragonfly ContextShade.
+
+ Args:
+ host_shade: A dragonfly_core ContextShade object that hosts these properties.
+ is_vegetation: Boolean to note whether the shade represents a tree canopy,
+ in which case, it will be incorporated into the simulation as tree
+ cover. (Default: False).
+
+ Properties:
+ * host
+ * is_vegetation
+ """
+
+ __slots__=('_host','_is_vegetation')
+
+ def__init__(self,host_shade,is_vegetation=False):
+"""Initialize ContextShade UWG properties."""
+ self._host=host_shade
+ self.is_vegetation=is_vegetation
+
+ @property
+ defhost(self):
+"""Get the Shade object hosting these properties."""
+ returnself._host
+
+ @property
+ defis_vegetation(self):
+"""Get or set a boolean for whether the shade represents a tree canopy."""
+ returnself._is_vegetation
+
+ @is_vegetation.setter
+ defis_vegetation(self,value):
+ self._is_vegetation=bool(value)
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data,host):
+"""Create ContextShadeUWGProperties from a dictionary.
+
+ Note that the dictionary must be a non-abridged version for this
+ classmethod to work.
+
+ Args:
+ data: A dictionary representation of ContextShadeUWGProperties.
+ host: A ContextShade object that hosts these properties.
+ """
+ assertdata['type']=='ContextShadeUWGProperties', \
+ 'Expected ContextShadeUWGProperties. Got {}.'.format(data['type'])
+ is_veg=data['is_vegetation']if'is_vegetation'indataelseFalse
+ returncls(host,is_veg)
+
+
+
+[docs]
+ defapply_properties_from_dict(self,abridged_data):
+"""Apply properties from a ContextShadeUWGPropertiesAbridged dictionary.
+
+ Args:
+ abridged_data: A ContextShadeUWGPropertiesAbridged dictionary (typically
+ coming from a Model).
+ """
+ if'is_vegetation'inabridged_data:
+ self.is_vegetation=abridged_data['is_vegetation']
+
+
+
+[docs]
+ defto_dict(self,abridged=False):
+"""Return UWG properties as a dictionary.
+
+ Args:
+ abridged: Boolean to note whether the full dictionary describing the
+ object should be returned (False) or just an abridged version (True).
+ Default: False.
+ """
+ base={'uwg':{}}
+ base['uwg']['type']='ContextShadeUWGProperties'ifnot \
+ abridgedelse'ContextShadeUWGPropertiesAbridged'
+ base['uwg']['is_vegetation']=self.is_vegetation
+ returnbase
+
+
+
+[docs]
+ defduplicate(self,new_host=None):
+"""Get a copy of this object.
+
+ new_host: A new ContextShade object that hosts these properties.
+ If None, the properties will be duplicated with the same host.
+ """
+ _host=new_hostorself._host
+ returnContextShadeUWGProperties(_host,self._is_vegetation)
+[docs]
+classModelUWGProperties(object):
+"""UWG Properties for Dragonfly Model.
+
+ Args:
+ host: A dragonfly_core Model object that hosts these properties.
+ terrain: A Terrain object that dictates the properties of the street and
+ ground beneath the buildings. If None, a default terrain object will be
+ generated by analysing all of the buildings in the Model and drawing
+ a bounding rectangle in the XY plane around them. (Default: None).
+ traffic: A TrafficParameter object that defines the activity and
+ intensity of traffic within the urban street canyons. If None,
+ traffic intensity will be approximated using the average building
+ story count along with a generic traffic schedule. (Default: None).
+ tree_coverage_fraction: A number from 0 to 1 that defines the fraction of the
+ exposed terrain covered by trees. If Autocalculate, it will be determined
+ by evaluating the horizontal area of all ContextShade geometry that has
+ a true is_vegetation property. (Default: autocalculate).
+ grass_coverage_fraction: A number from 0 to 1 that defines the fraction
+ of the exposed terrain that is covered by grass or shrubs.
+ Anything not covered in grass is assumed to be pavement. (Default: 0).
+
+ Properties:
+ * host
+ * terrain
+ * traffic
+ * tree_coverage_fraction
+ * grass_coverage_fraction
+ * footprint_density
+ * facade_to_site
+ * exposed_ground_area
+ * is_tree_coverage_autocalcualted
+ """
+
+ __slots__=('_host','_terrain','_traffic','_tree_coverage_fraction',
+ '_grass_coverage_fraction')
+
+ def__init__(self,host,terrain=None,traffic=None,
+ tree_coverage_fraction=autocalculate,grass_coverage_fraction=0):
+"""Initialize Model UWG properties."""
+ self._host=host
+ self.terrain=terrain
+ self.traffic=traffic
+ self.tree_coverage_fraction=tree_coverage_fraction
+ self.grass_coverage_fraction=grass_coverage_fraction
+
+ @property
+ defhost(self):
+"""Get the Model object hosting these properties."""
+ returnself._host
+
+ @property
+ defterrain(self):
+"""Get or set a Terrain object that dictates the properties of the ground."""
+ ifself._terrainisNone:
+ returnTerrain.from_building_bounding_rect(self.host.buildings)
+ returnself._terrain
+
+ @terrain.setter
+ defterrain(self,value):
+ ifvalueisnotNone:
+ assertisinstance(value,Terrain),'Expected Terrain object for ' \
+ 'ModelUWGProperties.terrain. Got {}.'.format(type(value))
+ self._terrain=value
+
+ @property
+ deftraffic(self):
+"""Get or set a TrafficParameter object that dictates the street traffic."""
+ returnself._traffic
+
+ @traffic.setter
+ deftraffic(self,value):
+ ifvalueisnotNone:
+ assertisinstance(value,TrafficParameter),'Expected TrafficParameter' \
+ ' object for ModelUWGProperties.traffic. Got {}.'.format(type(value))
+ self._traffic=valueifvalueisnotNoneelseTrafficParameter()
+
+ @property
+ deftree_coverage_fraction(self):
+"""Get or set the fraction of the exposed site area covered in trees."""
+ ifself._tree_coverage_fractionisNone:
+ returnself._autocalcualted_tree_coverage(self.exposed_ground_area)
+ returnself._tree_coverage_fraction
+
+ @tree_coverage_fraction.setter
+ deftree_coverage_fraction(self,value):
+ ifvalue==autocalculate:
+ self._tree_coverage_fraction=None
+ else:
+ self._tree_coverage_fraction= \
+ float_in_range(value,0,1,'tree_coverage_fraction')
+
+ @property
+ defgrass_coverage_fraction(self):
+"""Get or set the fraction of the exposed site area covered in grass or shrubs.
+
+ Anything not covered in grass is assumed to be pavement.
+ """
+ returnself._grass_coverage_fraction
+
+ @grass_coverage_fraction.setter
+ defgrass_coverage_fraction(self,value):
+ self._grass_coverage_fraction= \
+ float_in_range(value,0,1,'grass_coverage_fraction')
+
+ @property
+ deffootprint_density(self):
+"""Get a fractional number for the footprint density of the model."""
+ returnself.host.footprint_area/self.terrain.horizontal_area
+
+ @property
+ deffacade_to_site(self):
+"""Get a fractional number for the ratio between the facade are and site area."""
+ returnself.host.exterior_wall_area/self.terrain.horizontal_area
+
+ @property
+ defexposed_ground_area(self):
+"""Get the area of the terrain exposed to the outdoor air."""
+ returnself.terrain.horizontal_area-self.host.footprint_area
+
+ @property
+ defis_tree_coverage_autocalcualted(self):
+"""Get a boolean for whether tree coverage is autocalcualted from Context."""
+ returnself._tree_coverage_fractionisNone
+
+
+[docs]
+ defgrass_coverage_from_geometry(self,grass_geometry):
+"""Set this object's grass_coverage_fraction using an array of Face3Ds.
+
+ Args:
+ grass_geometry: An array of Face3Ds that represent grass surfaces.
+ """
+ grass_area=self.compute_horizontal_area(grass_geometry)
+ g_frac=grass_area/self.exposed_ground_area
+ self.grass_coverage_fraction=g_fracifg_frac<1else1
+
+
+
+[docs]
+ defaverage_shgc(self,climate_zone):
+"""Get the average SHGC across all buildings in the model.
+
+ Args:
+ climate_zone: Text for the ASHRAE climate zone, which must include
+ the humidity letter (eg. "4A") unless it is climate zone 7 or 8.
+ """
+ ext_ap_areas=[bldg.exterior_aperture_areaforbldginself.host.buildings]
+ total_area=sum(ext_ap_areas)
+ try:
+ ext_ap_weights=[area/total_areaforareainext_ap_areas]
+ exceptZeroDivisionError:# no apertures in model; just use dummy shgc
+ return0.4
+ shgc=0
+ forbldg,weightinzip(self.host.buildings,ext_ap_weights):
+ ifbldg.properties.uwg._shgcisNone:
+ shgc+=bldg.properties.uwg.default_shgc(climate_zone)*weight
+ else:
+ shgc+=bldg.properties.uwg._shgc*weight
+ returnshgc
+
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Move these properties along a vector.
+
+ Args:
+ moving_vec: A ladybug_geometry Vector3D with the direction and distance
+ to move the object.
+ """
+ ifself._terrainisnotNone:
+ self._terrain.move(moving_vec)
+
+
+
+[docs]
+ defrotate_xy(self,angle,origin):
+"""Rotate this Terrain counterclockwise in the XY plane by a certain angle.
+
+ Args:
+ angle: An angle in degrees.
+ origin: A ladybug_geometry Point3D for the origin around which the
+ object will be rotated.
+ """
+ ifself._terrainisnotNone:
+ self._terrain.rotate_xy(angle,origin)
+
+
+
+[docs]
+ defreflect(self,plane):
+"""Reflect this Terrain across a plane.
+
+ Args:
+ plane: A ladybug_geometry Plane across which the object will be reflected.
+ """
+ ifself._terrainisnotNone:
+ self._terrain.reflect(plane)
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale this Terrain by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the object should be scaled.
+ origin: A ladybug_geometry Point3D representing the origin from which
+ to scale. If None, it will be scaled from the World origin (0, 0, 0).
+ """
+ ifself._terrainisnotNone:
+ self._terrain.scale(factor,origin)
+
+
+
+[docs]
+ defapply_properties_from_dict(self,data):
+"""Apply the uwg properties of a dictionary to the host Model of this object.
+
+ Args:
+ data: A dictionary representation of an entire dragonfly-core Model.
+ Note that this dictionary must have ModelUWGProperties in order
+ for this method to successfully apply the uwg properties.
+ """
+ # check that UWG properties exist and apply the global ones to this object
+ assert'uwg'indata['properties'], \
+ 'Dictionary possesses no ModelUWGProperties.'
+ uwg_data=data['properties']['uwg']
+ if'terrain'inuwg_dataanduwg_data['terrain']isnotNone:
+ self.terrain=Terrain.from_dict(uwg_data['terrain'])
+ if'traffic'inuwg_dataanduwg_data['traffic']isnotNone:
+ self.traffic=TrafficParameter.from_dict(uwg_data['traffic'])
+ if'tree_coverage_fraction'inuwg_dataand \
+ uwg_data['tree_coverage_fraction']!=autocalculate.to_dict():
+ self.tree_coverage_fraction=uwg_data['tree_coverage_fraction']
+ if'grass_coverage_fraction'inuwg_data:
+ self.grass_coverage_fraction=uwg_data['grass_coverage_fraction']
+
+ # collect lists of uwg property dictionaries
+ building_u_dicts,_,_,context_u_dicts= \
+ model_extension_dicts(data,'uwg',[],[],[],[])
+
+ # apply uwg properties to objects using the uwg property dictionaries
+ forbldg,b_dictinzip(self.host.buildings,building_u_dicts):
+ ifb_dictisnotNone:
+ bldg.properties.uwg.apply_properties_from_dict(b_dict)
+ forshade,s_dictinzip(self.host.context_shades,context_u_dicts):
+ ifs_dictisnotNone:
+ shade.properties.uwg.apply_properties_from_dict(s_dict)
+
+
+
+[docs]
+ defto_dict(self):
+"""Return Model UWG properties as a dictionary."""
+ base={'uwg':{'type':'ModelUWGProperties'}}
+ ifself._terrainisnotNone:
+ base['uwg']['terrain']=self._terrain.to_dict()
+ base['uwg']['traffic']=self.traffic.to_dict()
+ ifself._tree_coverage_fractionisnotNone:
+ base['uwg']['tree_coverage_fraction']=self.tree_coverage_fraction
+ base['uwg']['grass_coverage_fraction']=self.grass_coverage_fraction
+ returnbase
+
+
+
+[docs]
+ defto_uwg_dict(self):
+"""Get a dictionary following the input schema of the UWG.
+
+ This dictionary can be serialized into a JSON in order to be run through
+ the UWG. Note that this dictionary will only include the properties that
+ the dragonfly Model object possesses and will lack all of those provided
+ by the UWGSimulationParameter object. For fully simulate-able UWG
+ input, the Model.to.uwg method should be used. The keys of the dictionary
+ output by this method include the following.
+
+ * bldheight
+ * blddensity
+ * vertohor
+ * grasscover
+ * treecover
+ * bld
+ * h_mix
+ * albroof
+ * vegroof
+ * glzr
+ * albwall
+ * flr_h
+ * charlength
+ * albroad
+ * droad
+ * kroad
+ * croad
+ * sensanth
+ * schtraffic
+
+ """
+ # check that the model units are meters before extracting outputs
+ assertself.host.units=='Meters', \
+ 'Model units must be in Meters to use to_uwg_dict.'
+
+ # get the geometry properties on a per-building level
+ floors=[bldg.floor_areaforbldginself.host._buildings]
+ footprints=[bldg.footprint_areaforbldginself.host._buildings]
+ walls=[bldg.exterior_wall_areaforbldginself.host._buildings]
+
+ total_floor,total_foot,total_wall=sum(floors),sum(footprints),sum(walls)
+ floor_weights=[area/total_floorforareainfloors]
+ foot_weights=[area/total_footforareainfootprints]
+ walls_weights=[area/total_wallforareainwalls]
+
+ # do some geometry computations with checks
+ terrain=self.terrain# request once to potentially avoid regenerating it
+ site_area=terrain.horizontal_area
+ density=total_foot/site_area
+ assertdensity<=1,'Building footprint areas [{} m2] cannot be larger than ' \
+ 'the terrain area [{} m2].'.format(total_foot,site_area)
+ tree=self._tree_coverage_fraction
+ ifself._tree_coverage_fractionisNone:
+ ground_area=site_area-total_foot
+ tree=self._autocalcualted_tree_coverage(ground_area)
+ tree=tree*(1-density)# uwg expcts fraction for whole area
+ grass=self.grass_coverage_fraction*(1-density)# uwg expcts for whole area
+ average_height=self.host.average_height_above_ground
+ story_count=self.host.average_story_count_above_ground
+ sens_anth=self.traffic._watts_per_area
+ ifself.traffic._watts_per_areaisNone:
+ sens_anth=self._autocalculated_traffic(story_count)
+
+ # create the dictionary
+ base={'type':'UWG'}
+ base['bldheight']=average_height
+ base['blddensity']=densityifdensity<1else0.99
+ base['vertohor']=round(sum(walls)/site_area,5)
+ base['treecover']=round(tree,5)
+ base['grasscover']=round(grass,5)iftree+grass+density<=1 \
+ elseround(1-tree-density,5)
+ base['bld']=self._create_bld_matrix(floor_weights)
+ base['h_mix']=self._weighted_property('fract_heat_to_canyon',floor_weights)
+ base['albroof']=self._weighted_property('roof_albedo',foot_weights)
+ base['vegroof']=self._weighted_property('roof_veg_fraction',foot_weights)
+ base['glzr']=round(self.host.exterior_aperture_area/total_wall,5)
+ base['albwall']=self._weighted_property('wall_albedo',walls_weights)
+ base['flr_h']=round(average_height/story_count,5)
+ base['charlength']=round(terrain.characteristic_length,5)
+ base['albroad']=round(terrain.pavement_albedo,5)
+ base['droad']=round(terrain.pavement_thickness,5)
+ base['kroad']=round(terrain.pavement_conductivity,5)
+ base['croad']=round(terrain.pavement_heat_capacity,5)
+ base['sensanth']=round(sens_anth,5)
+ base['schtraffic']=[self.traffic.weekday_schedule,
+ self.traffic.saturday_schedule,
+ self.traffic.sunday_schedule]
+ returnbase
+
+
+
+[docs]
+ defduplicate(self,new_host=None):
+"""Get a copy of this Model.
+
+ Args:
+ new_host: A new Model object that hosts these properties.
+ If None, the properties will be duplicated with the same host.
+ """
+ _host=new_hostorself._host
+ new_obj=ModelUWGProperties(_host)
+ ifself._terrainisnotNone:
+ new_obj._terrain=self._terrain.duplicate()
+ new_obj._traffic=self._traffic.duplicate()
+ new_obj._tree_coverage_fraction=self._tree_coverage_fraction
+ new_obj._grass_coverage_fraction=self._grass_coverage_fraction
+ returnnew_obj
+
+
+
+[docs]
+ @staticmethod
+ defcompute_horizontal_area(face3ds):
+"""Get the area of a list of Face3D in the XY Plane.
+
+ This is useful for taking geometry representing grass or pavement and
+ turning it into a number for grass_coverage_fraction.
+ """
+ poly2d=Terrain._face3d_to_polygon2d(face3ds)
+ returnsum([geo.areaforgeoinpoly2d])
+
+
+ def_create_bld_matrix(self,floor_area_weights):
+"""Create the matrix of building programs and vintages for the uwg_dict."""
+ bld_dict={}
+ forbldg,weightinzip(self.host._buildings,floor_area_weights):
+ uwg_prop=bldg.properties.uwg
+ key='{}_{}'.format(uwg_prop.program,uwg_prop.vintage)
+ try:
+ bld_dict[key][2]+=weight
+ exceptKeyError:# first time we have this program and vintage
+ bld_dict[key]=[uwg_prop.program_uwg,uwg_prop.vintage_uwg,weight]
+ # round all weight values to avoid tolerance issues
+ forvalinbld_dict:
+ bld_dict[val][2]=round(bld_dict[val][2],3)
+ returntuple(bld_dict.values())
+
+ def_autocalcualted_tree_coverage(self,ground_area):
+"""Autocalculate the tree coverage from the model context shades."""
+ veg_shds,mesh_area=[],0
+ forshdinself.host.context_shades:
+ ifshd.properties.uwg.is_vegetation:
+ ifisinstance(shd.geometry,Face3D):
+ veg_shds.extend(shd.geometry)
+ else:
+ mesh_area+=shd.geometry.area
+ tree_area=self.compute_horizontal_area(veg_shds)+mesh_area
+ ifground_area<=0:
+ return0
+ returntree_area/ground_areaiftree_area/ground_area<=1else1
+
+ def_weighted_property(self,attribute,weights):
+ weight_val=sum([getattr(bldg.properties.uwg,attribute)*w
+ forbldg,winzip(self.host._buildings,weights)])
+ returnround(weight_val,5)
+
+ @staticmethod
+ def_autocalculated_traffic(story_count):
+"""Autocalculate the traffic wattage from the average story count."""
+ ifstory_count<=3:
+ return4
+ ifstory_count<=6:
+ return10
+ return20
+
+
+[docs]
+classRoom2DUWGProperties(object):
+"""UWG Properties for Dragonfly Room2D.
+
+ Args:
+ host: A dragonfly_core Room2D object that hosts these properties.
+
+ Properties:
+ * host
+ """
+
+ __slots__=('_host',)
+
+ def__init__(self,host):
+"""Initialize Room2D UWG properties."""
+ self._host=host
+
+ @property
+ defhost(self):
+"""Get the Room2D object hosting these properties."""
+ returnself._host
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data,host):
+"""Create Room2DUWGProperties from a dictionary.
+
+ Note that the dictionary must be a non-abridged version for this
+ classmethod to work.
+
+ Args:
+ data: A dictionary representation of Room2DUWGProperties.
+ host: A Room2D object that hosts these properties.
+ """
+ assertdata['type']=='Room2DUWGProperties', \
+ 'Expected Room2DUWGProperties. Got {}.'.format(data['type'])
+ new_prop=cls(host)
+ returnnew_prop
+
+
+
+[docs]
+ defapply_properties_from_dict(self,abridged_data):
+"""Apply properties from a Room2DUWGPropertiesAbridged dictionary.
+
+ Args:
+ abridged_data: A Room2DUWGPropertiesAbridged dictionary (typically
+ coming from a Model).
+ """
+ pass# currently no properties to apply
+
+
+
+[docs]
+ defto_dict(self,abridged=False):
+"""Return Room2D UWG properties as a dictionary.
+
+ Args:
+ abridged: Boolean for whether the full dictionary of the Room2D should
+ be written (False) or just the identifier of the the individual
+ properties (True). Default: False.
+ """
+ base={'uwg':{}}
+ base['uwg']['type']='Room2DUWGProperties'ifnot \
+ abridgedelse'Room2DUWGPropertiesAbridged'
+ returnbase
+
+
+
+[docs]
+ defduplicate(self,new_host=None):
+"""Get a copy of this object.
+
+ new_host: A new Room2D object that hosts these properties.
+ If None, the properties will be duplicated with the same host.
+ """
+ _host=new_hostorself._host
+ returnRoom2DUWGProperties(_host)
+[docs]
+classStoryUWGProperties(object):
+"""UWG Properties for Dragonfly Story.
+
+ Args:
+ host: A dragonfly_core Story object that hosts these properties.
+
+ Properties:
+ * host
+ """
+
+ __slots__=('_host',)
+
+ def__init__(self,host):
+"""Initialize Story UWG properties."""
+ self._host=host
+
+ @property
+ defhost(self):
+"""Get the Story object hosting these properties."""
+ returnself._host
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data,host):
+"""Create StoryUWGProperties from a dictionary.
+
+ Note that the dictionary must be a non-abridged version for this
+ classmethod to work.
+
+ Args:
+ data: A dictionary representation of StoryUWGProperties.
+ host: A Story object that hosts these properties.
+ """
+ assertdata['type']=='StoryUWGProperties', \
+ 'Expected StoryUWGProperties. Got {}.'.format(data['type'])
+ new_prop=cls(host)
+ returnnew_prop
+
+
+
+[docs]
+ defapply_properties_from_dict(self,abridged_data):
+"""Apply properties from a StoryUWGPropertiesAbridged dictionary.
+
+ Args:
+ abridged_data: A StoryUWGPropertiesAbridged dictionary (typically
+ coming from a Model).
+ """
+ pass# currently no properties to apply
+
+
+
+[docs]
+ defto_dict(self,abridged=False):
+"""Return Story UWG properties as a dictionary.
+
+ Args:
+ abridged: Boolean for whether the full dictionary of the Story should
+ be written (False) or just the identifier of the the individual
+ properties (True). Default: False.
+ """
+ base={'uwg':{}}
+ base['uwg']['type']='StoryUWGProperties'ifnot \
+ abridgedelse'StoryUWGPropertiesAbridged'
+ returnbase
+
+
+
+[docs]
+ defduplicate(self,new_host=None):
+"""Get a copy of this object.
+
+ new_host: A new Story object that hosts these properties.
+ If None, the properties will be duplicated with the same host.
+ """
+ _host=new_hostorself._host
+ returnStoryUWGProperties(_host)
+# coding=utf-8
+"""Module for running models through the Urban Weather Generator (UWG)."""
+from__future__importdivision
+
+importos
+importjson
+importsubprocess
+
+fromhoneybee.configimportfoldersashb_folders
+fromladybug.configimportfoldersaslb_folders
+fromladybug.futilimportwrite_to_file,preparedir
+
+
+
+[docs]
+defrun_uwg(model,epw_file_path,simulation_parameter=None,directory=None,
+ silent=False):
+"""Run a UWG dictionary file through the UWG on any operating system.
+
+ Args:
+ model: A Dragonfly Model to be used to morph the EPW for the urban area.
+ epw_file_path: The full path to an EPW file.
+ simulation_parameter: A UWGSimulationParameter object that dictates various
+ settings about the UWG simulation. If None, default parameters will
+ be generated. (Default: None).
+ directory: Text for the directory into which the the uwg JSON and morphed
+ urban EPW will be written. If None, it will be written into the
+ ladybug default_epw_folder within a subfolder bearing the name
+ of the dragonfly Model. (Default: None).
+ silent: Boolean to note whether the simulation should be run silently.
+ This only has an effect on Windows simulations since Unix-based
+ simulations always use shell and are always silent (Default: False).
+
+ Returns:
+ The following files output from the UWG CLI run
+
+ - uwg_json -- Path to a .json file derived from the input uwg_dict.
+
+ - epw -- File path to the morphed EPW. Will be None if the UWG
+ failed to run.
+ """
+ # get the name of the EPW and the directory into which the urban epw will be written
+ epw_file_path=os.path.abspath(epw_file_path)
+ epw_name='{}.epw'.format(model.identifier)
+ ifdirectoryisNone:
+ directory=os.path.join(lb_folders.default_epw_folder,model.identifier)
+ preparedir(directory,remove_content=False)
+
+ # write the model to a UWG dictionary
+ uwg_dict=model.to.uwg(model,epw_file_path,simulation_parameter)
+ uwg_json=os.path.join(directory,'{}_uwg.json'.format(model.identifier))
+ withopen(uwg_json,'w')asfp:
+ json.dump(uwg_dict,fp,indent=4)
+
+ # run the simulation
+ ifos.name=='nt':# we are on Windows
+ epw=_run_uwg_windows(uwg_json,epw_file_path,epw_name,silent)
+ else:# we are on Mac, Linux, or some other unix-based system
+ epw=_run_uwg_unix(uwg_json,epw_file_path,epw_name)
+ returnuwg_json,epw
+
+
+
+def_run_uwg_windows(uwg_json_path,epw_file_path,epw_name,silent=False):
+"""Run a JSON file through the UWG on a Windows-based operating system.
+
+ A batch file will be used to run the simulation unless silent is True.
+
+ Args:
+ uwg_json_path: The full path to a UWG JSON file.
+ epw_file_path: The full path to an EPW file.
+ epw_name: Text for the name of the EPW file.
+ silent: Boolean to note whether the simulation should be run silently
+ (without the batch window). If so, the simulation will be run using
+ subprocess with shell set to True. (Default: False).
+
+ Returns:
+ File path to the morphed EPW. Will be None if the UWG failed to run.
+ """
+ directory=os.path.dirname(uwg_json_path)
+ custom_env=os.environ.copy()
+ custom_env['PYTHONHOME']=''
+ ifnotsilent:# run the simulations with shell=False
+ command='"{}" -m uwg simulate model "{}" "{}" --new-epw-dir "{}" ' \
+ '--new-epw-name "{}"'.format(
+ hb_folders.python_exe_path,uwg_json_path,
+ epw_file_path,directory,epw_name)
+ process=subprocess.Popen(
+ command,stderr=subprocess.PIPE,shell=False,env=custom_env)
+ else:# run the simulation using subprocess with shell=True
+ cmds=[hb_folders.python_exe_path,'-m','uwg','simulate','model',
+ uwg_json_path,epw_file_path,'--new-epw-dir',directory,
+ '--new-epw-name',epw_name]
+ process=subprocess.Popen(
+ cmds,stderr=subprocess.PIPE,shell=True,env=custom_env)
+ _,stderr=process.communicate()
+ rc=process.returncode
+ ifisinstance(rc,int)andrc!=0:
+ raiseRuntimeError('The UWG failed to run:\n{}'.format(stderr))
+ epw_file=os.path.join(directory,epw_name)
+ returnepw_fileifos.path.isfile(epw_file)elseNone
+
+
+def_run_uwg_unix(uwg_json_path,epw_file_path,epw_name):
+"""Run a JSON file through the UWG on a Unix-based operating system.
+
+ This includes both Mac OS and Linux since a shell will be used to run
+ the simulation.
+
+ Args:
+ uwg_json_path: The full path to a UWG JSON file.
+ epw_file_path: The full path to an EPW file.
+ epw_name: Text for the name of the EPW file.
+
+ Returns:
+ File path to the morphed EPW. Will be None if the UWG failed to run.
+ """
+ directory=os.path.dirname(uwg_json_path)
+ # write a shell file
+ shell='#!/usr/bin/env bash\n\ncd "{}"\n{} -m uwg simulate model "{}" "{}" ' \
+ '--new-epw-dir "{}" --new-epw-name "{}"'.format(
+ directory,hb_folders.python_exe_path,uwg_json_path,
+ epw_file_path,directory,epw_name)
+ shell_file=os.path.join(directory,'in.sh')
+ write_to_file(shell_file,shell,True)
+
+ # make the shell script executable using subprocess.check_call
+ # this is more reliable than native Python chmod on Mac
+ subprocess.check_call(['chmod','u+x',shell_file])
+
+ # run the shell script
+ subprocess.call(shell_file)
+
+ epw_file=os.path.join(directory,epw_name)
+ returnepw_fileifos.path.isfile(epw_file)elseNone
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/dragonfly_uwg/simulation/boundary.html b/docs/_modules/dragonfly_uwg/simulation/boundary.html
new file mode 100644
index 00000000..a4ab0941
--- /dev/null
+++ b/docs/_modules/dragonfly_uwg/simulation/boundary.html
@@ -0,0 +1,574 @@
+
+
+
+
+
+
+ dragonfly_uwg.simulation.boundary — dragonfly-uwg documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+classBoundaryLayerParameter(object):
+"""Properties of the urban boundary layer.
+
+ Args:
+ 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 meteorological conditions
+ are stable and representative of the overall urban area.
+ Typically, this boundary layer height increases with the
+ height of the buildings. (Default: 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 meteorological
+ conditions are stable and representative of the overall
+ urban area. Typically, this boundary layer height increases with
+ the height of the buildings. (Default: 80 meters).
+ inversion_height: A number that represents the height in meters at which
+ the vertical profile of potential temperature becomes stable.
+ Can be determined by flying helium balloons equipped
+ with temperature sensors and recording the air temperatures
+ at different heights. (Default: 150 meters).
+ circulation_coefficient: A number representing the circulation
+ coefficient. (Default: 1.2, per Bueno (2012)).
+ exchange_coefficient: A number representing the exchange
+ coefficient. (Default: 1.0, per Bueno (2014)).
+ """
+
+ __slots__=('_day_boundary_layer_height','_night_boundary_layer_height',
+ '_inversion_height','_circulation_coefficient',
+ '_exchange_coefficient')
+
+ def__init__(self,day_boundary_layer_height=1000,night_boundary_layer_height=80,
+ inversion_height=150,
+ circulation_coefficient=1.2,exchange_coefficient=1.0):
+"""Initialize Boundary Layer parameters"""
+ self.day_boundary_layer_height=day_boundary_layer_height
+ self.night_boundary_layer_height=night_boundary_layer_height
+ self.inversion_height=inversion_height
+ self.circulation_coefficient=circulation_coefficient
+ self.exchange_coefficient=exchange_coefficient
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a BoundaryLayerParameter object from a dictionary
+
+ Args:
+ data: A dictionary representation of an BoundaryLayerParameter object
+ in the format below.
+
+ .. code-block:: python
+
+ {
+ 'type': 'BoundaryLayerParameter',
+ 'day_boundary_layer_height': 1000, # float for height in meters
+ 'night_boundary_layer_height': 80, # float for height in meters
+ 'inversion_height': 150, # float for inversion layer height
+ 'circulation_coefficient': 1.2, # float for circulation coefficient
+ 'exchange_coefficient': 1.0 # float for exchange coefficient
+ }
+ """
+ day=data['day_boundary_layer_height'] \
+ if'day_boundary_layer_height'indataelse1000
+ night=data['night_boundary_layer_height'] \
+ if'night_boundary_layer_height'indataelse80
+ inv=data['inversion_height']if'inversion_height'indataelse150
+ circ=data['circulation_coefficient'] \
+ if'circulation_coefficient'indataelse1.2
+ exch=data['exchange_coefficient'] \
+ if'exchange_coefficient'indataelse1.0
+ returncls(day,night,inv,circ,exch)
+
+
+ @property
+ defday_boundary_layer_height(self):
+"""Get or set a number for the daytime boundary layer height in meters."""
+ returnself._day_boundary_layer_height
+
+ @day_boundary_layer_height.setter
+ defday_boundary_layer_height(self,value):
+ self._day_boundary_layer_height= \
+ float_positive(value,'day_boundary_layer_height')
+
+ @property
+ defnight_boundary_layer_height(self):
+"""Get or set a number for the nighttime boundary layer height i meters."""
+ returnself._night_boundary_layer_height
+
+ @night_boundary_layer_height.setter
+ defnight_boundary_layer_height(self,value):
+ self._night_boundary_layer_height= \
+ float_positive(value,'night_boundary_layer_height')
+
+ @property
+ definversion_height(self):
+"""Get or set a number for the inversion height in meters."""
+ returnself._inversion_height
+
+ @inversion_height.setter
+ definversion_height(self,value):
+ self._inversion_height=float_positive(value,'inversion_height')
+
+ @property
+ defcirculation_coefficient(self):
+"""Get or set a number for the circulation coefficient."""
+ returnself._circulation_coefficient
+
+ @circulation_coefficient.setter
+ defcirculation_coefficient(self,value):
+ self._circulation_coefficient=float_positive(value,'circulation_coefficient')
+
+ @property
+ defexchange_coefficient(self):
+"""Get or set the exchange coefficient."""
+ returnself._exchange_coefficient
+
+ @exchange_coefficient.setter
+ defexchange_coefficient(self,value):
+ self._exchange_coefficient=float_positive(value,'exchange_coefficient')
+
+
+[docs]
+classUWGSimulationParameter(object):
+"""Complete set of UWG Simulation Settings.
+
+ Args:
+ climate_zone: Text for the ASHRAE climate zone, including the letter for
+ humidity classification (eg. "4A"). This is used to set default
+ constructions for various buildings. If set to autocalculate,
+ the climate zone will be estimated from analysis of the epw to be
+ morphed for simulation. (Default: autocalculate).
+ run_period: A UWGRunPeriod object to describe the time period over which to
+ run the simulation. If None, the simulation will be run for the whole
+ year. (Default: None).
+ timestep: An integer for the number of timesteps per hour at which the
+ calculation will be run. (Default: 12).
+ vegetation_parameter: A VegetationParameter to specify the behavior of
+ vegetation in the urban area. If None, generic vegetation parameters
+ will be generated. (Default: None).
+ reference_epw_site: A ReferenceEPWSite to specify the properties of the
+ reference site where the input rural EPW was recorded. If None, generic
+ airport properties will be generated. (Default: None).
+ boundary_layer_parameter: A BoundaryLayerParameter to specify the properties
+ of the urban boundary layer. If None, generic boundary layer parameters
+ will be generated. (Default: None).
+ """
+ __slots__=('_climate_zone','_run_period','_timestep','_vegetation_parameter',
+ '_reference_epw_site','_boundary_layer_parameter')
+
+ VALIDTIMESTEPS=(1,2,3,4,5,6,10,12,15,20,30,60)
+ VALIDZONES=('1A','1B','2A','2B','3A','3B','3C','4A','4B','4C',
+ '5A','5B','5C','6A','6B','7','8')
+
+ def__init__(self,climate_zone=autocalculate,run_period=None,timestep=12,
+ vegetation_parameter=None,reference_epw_site=None,
+ boundary_layer_parameter=None):
+"""Initialize UWGSimulationParameter"""
+ self.climate_zone=climate_zone
+ self.run_period=run_period
+ self.timestep=timestep
+ self.vegetation_parameter=vegetation_parameter
+ self.reference_epw_site=reference_epw_site
+ self.boundary_layer_parameter=boundary_layer_parameter
+
+ @property
+ defclimate_zone(self):
+"""Get or set a text for the ASHRAE climate zone."""
+ returnself._climate_zoneifself._climate_zoneisnotNoneelseautocalculate
+
+ @climate_zone.setter
+ defclimate_zone(self,value):
+ ifvalue==autocalculate:
+ self._climate_zone=None
+ else:
+ assertvalueinself.VALIDZONES,'UWGSimulationParameter climate_zone ' \
+ '"{}" is invalid.\nMust be one of the following:{}'.format(
+ value,self.VALIDZONES)
+ self._climate_zone=value
+
+ @property
+ defrun_period(self):
+"""Get or set a UWGRunPeriod object for the time period to run the simulation."""
+ returnself._run_period
+
+ @run_period.setter
+ defrun_period(self,value):
+ ifvalueisnotNone:
+ assertisinstance(value,UWGRunPeriod),'Expected UWGRunPeriod for ' \
+ 'UWGSimulationParameter run_period. Got {}.'.format(type(value))
+ self._run_period=value
+ else:
+ self._run_period=UWGRunPeriod()
+
+ @property
+ deftimestep(self):
+"""Get or set a integer for the number of simulation timesteps per hour."""
+ returnself._timestep
+
+ @timestep.setter
+ deftimestep(self,value):
+ value=int_positive(value,'simulation parameter timestep')
+ assertvalueinself.VALIDTIMESTEPS,'UWGSimulationParameter timestep "{}" is ' \
+ 'invalid. Must be one of the following:{}'.format(value,self.VALIDTIMESTEPS)
+ self._timestep=value
+
+ @property
+ defvegetation_parameter(self):
+"""Get or set a VegetationParameter object for the behavior of vegetation."""
+ returnself._vegetation_parameter
+
+ @vegetation_parameter.setter
+ defvegetation_parameter(self,value):
+ ifvalueisnotNone:
+ assertisinstance(value,VegetationParameter),'Expected ' \
+ 'VegetationParameter. Got {}.'.format(type(value))
+ self._vegetation_parameter=value
+ else:
+ self._vegetation_parameter=VegetationParameter()
+
+ @property
+ defreference_epw_site(self):
+"""Get or set a ReferenceEPWSite object for the properties of the rural EPW."""
+ returnself._reference_epw_site
+
+ @reference_epw_site.setter
+ defreference_epw_site(self,value):
+ ifvalueisnotNone:
+ assertisinstance(value,ReferenceEPWSite),'Expected ReferenceEPWSite ' \
+ 'for UWGSimulationParameter. Got {}.'.format(type(value))
+ self._reference_epw_site=value
+ else:
+ self._reference_epw_site=ReferenceEPWSite()
+
+ @property
+ defboundary_layer_parameter(self):
+"""Get or set a BoundaryLayerParameter object for the boundary layer properties.
+ """
+ returnself._boundary_layer_parameter
+
+ @boundary_layer_parameter.setter
+ defboundary_layer_parameter(self,value):
+ ifvalueisnotNone:
+ assertisinstance(value,BoundaryLayerParameter),'Expected ' \
+ 'BoundaryLayerParameter. Got {}.'.format(type(value))
+ self._boundary_layer_parameter=value
+ else:
+ self._boundary_layer_parameter=BoundaryLayerParameter()
+
+
+[docs]
+ defto_uwg_dict(self,epw_file):
+"""Get a dictionary following the input schema of the UWG.
+
+ Note that this dictionary will only include the properties that the
+ UWGSimulationParameter object possesses and will lack all of those provided
+ by the Model object. For fully simulate-able UWG input, the Model.to.uwg
+ method should be used. The keys of the dictionary output by this method
+ include the following.
+
+ * zone
+ * month
+ * day
+ * nday
+ * dtsim
+ * rurvegcover
+ * vegstart
+ * vegend
+ * albveg
+ * latgrss
+ * lattree
+ * h_ubl1
+ * h_ubl2
+ * h_ref
+ * h_temp
+ * h_wind
+ * c_circ
+ * c_exch
+ * h_obs
+
+ Args:
+ epw_file: File path to the EPW that will be morphed by the UWG. This
+ will be used to fill all autocalculated fields like the ASHRAE
+ climate zone and vegetation start/end.
+ """
+ # autocalculate any missing values from the epw_file
+ climate_zone=self._climate_zone
+ veg_start=self.vegetation_parameter._start_month
+ veg_end=self.vegetation_parameter._end_month
+ ifclimate_zoneisNoneorveg_startisNoneorveg_endisNone:
+ epw_obj=EPW(epw_file)
+ start_def,end_def=self._autocalc_start_end_vegetation(epw_obj)
+ veg_start=start_defifveg_startisNoneelseveg_start
+ veg_end=end_defifveg_endisNoneelseveg_end
+ climate_zone=epw_obj.ashrae_climate_zoneifclimate_zoneisNone \
+ elseclimate_zone
+
+ # create the uwg dictionary
+ base={}
+ base['zone']=climate_zone
+ base['month']=self.run_period.start_date.month
+ base['day']=self.run_period.start_date.day
+ base['nday']=self.run_period.day_count
+ base['dtsim']=int((60/self.timestep)*60)
+ base['vegstart']=veg_start
+ base['vegend']=veg_end
+ base['albveg']=self.vegetation_parameter.vegetation_albedo
+ base['latgrss']=self.vegetation_parameter.grass_latent_fraction
+ base['lattree']=self.vegetation_parameter.tree_latent_fraction
+ base['h_ubl1']=self.boundary_layer_parameter.day_boundary_layer_height
+ base['h_ubl2']=self.boundary_layer_parameter.night_boundary_layer_height
+ base['h_ref']=self.boundary_layer_parameter.inversion_height
+ base['c_circ']=self.boundary_layer_parameter.circulation_coefficient
+ base['c_exch']=self.boundary_layer_parameter.exchange_coefficient
+ base['rurvegcover']=self.reference_epw_site.vegetation_coverage
+ base['h_temp']=self.reference_epw_site.temp_measure_height
+ base['h_wind']=self.reference_epw_site.wind_measure_height
+ base['h_obs']=self.reference_epw_site.average_obstacle_height
+ returnbase
+
+
+
+[docs]
+ defduplicate(self):
+"""Get a copy of this object."""
+ returnself.__copy__()
+
+
+ @staticmethod
+ def_autocalc_start_end_vegetation(epw_obj,threshold_temp=10):
+"""Autocalculate the vegetation start and end month from an EPW."""
+ month_temps=epw_obj.dry_bulb_temperature.average_monthly()
+ veg_start,veg_end,veg_start_set=1,12,False
+ fori,tinenumerate(month_temps):
+ ift>threshold_tempandnotveg_start_set:
+ veg_start,veg_start_set=i+1,True
+ elift<threshold_tempandveg_start_set:
+ veg_end,veg_start_set=i+1,False
+ returnveg_start,veg_end
+
+ def__copy__(self):
+ returnUWGSimulationParameter(
+ self.climate_zone,self.run_period.duplicate(),self.timestep,
+ self.vegetation_parameter.duplicate(),self.reference_epw_site.duplicate(),
+ self.boundary_layer_parameter.duplicate())
+
+
+[docs]
+classReferenceEPWSite(object):
+"""Properties of the reference site where the input rural EPW was recorded.
+
+ Args:
+ 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. (Default: 0.1 m).
+ vegetation_coverage: A number between 0 and 1 that represents the fraction
+ of the reference EPW site that is covered in grass. (Default: 0.9).
+ temp_measure_height: A number that represents the height in meters at which
+ temperature is measured on the weather station. (Default: 10m, the
+ standard measurement height for US DoE EPW files).
+ wind_measure_height: A number that represents the height in meters at which
+ wind speed is measured on the weather station. (Default: 10m, the
+ standard measurement height for US DoE EPW files).
+ """
+ __slots__=('_average_obstacle_height','_vegetation_coverage',
+ '_temp_measure_height','_wind_measure_height')
+
+ def__init__(self,average_obstacle_height=0.1,vegetation_coverage=0.9,
+ temp_measure_height=10,wind_measure_height=10):
+"""Initialize ReferenceEPWSite parameters"""
+ self.average_obstacle_height=average_obstacle_height
+ self.vegetation_coverage=vegetation_coverage
+ self.temp_measure_height=temp_measure_height
+ self.wind_measure_height=wind_measure_height
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a ReferenceEPWSite object from a dictionary
+
+ Args:
+ data: A dictionary representation of an ReferenceEPWSite object
+ in the format below.
+
+ .. code-block:: python
+
+ {
+ 'type': 'ReferenceEPWSite',
+ 'average_obstacle_height': 10, # float for obstacle height in meters
+ 'vegetation_coverage': 0.95, # float for vegetation coverage between 0 and 1
+ 'temp_measure_height': 10, # float for temp measurement height in meters
+ 'wind_measure_height: 15 # float for wind measurement height in meters
+ }
+ """
+ ob_hgt=data['average_obstacle_height'] \
+ if'average_obstacle_height'indataelse0.1
+ veg_cov=data['vegetation_coverage'] \
+ if'vegetation_coverage'indataelse0.9
+ temp=data['temp_measure_height'] \
+ if'temp_measure_height'indataelse10
+ wind=data['wind_measure_height'] \
+ if'wind_measure_height'indataelse10
+ returncls(ob_hgt,veg_cov,temp,wind)
+
+
+ @property
+ defaverage_obstacle_height(self):
+"""Get or set a number for the average obstacle height in meters."""
+ returnself._average_obstacle_height
+
+ @average_obstacle_height.setter
+ defaverage_obstacle_height(self,value):
+ self._average_obstacle_height=float_positive(value,'average_obstacle_height')
+
+ @property
+ defvegetation_coverage(self):
+"""Get or set a fractional number for the vegetation coverage."""
+ returnself._vegetation_coverage
+
+ @vegetation_coverage.setter
+ defvegetation_coverage(self,value):
+ self._vegetation_coverage=float_in_range(value,0,1,'vegetation_coverage')
+
+ @property
+ deftemp_measure_height(self):
+"""Get or set a number for the temperature measurement height in meters."""
+ returnself._temp_measure_height
+
+ @temp_measure_height.setter
+ deftemp_measure_height(self,value):
+ self._temp_measure_height=float_positive(value,'temp_measure_height')
+
+ @property
+ defwind_measure_height(self):
+"""Get or set a number for the wind measurement height in meters."""
+ returnself._wind_measure_height
+
+ @wind_measure_height.setter
+ defwind_measure_height(self,value):
+ self._wind_measure_height=float_positive(value,'wind_measure_height')
+
+
+[docs]
+classUWGRunPeriod(object):
+"""UWG Simulation Run Period.
+
+ Args:
+ start_date: A ladybug Date object for the start of the simulation.
+ Must be before the end date and have a leap_year property matching the
+ end_date. (Default: 1 Jan).
+ end_date: A ladybug Date object for the end of the simulation.
+ Must be after the start date and have a leap_year property matching the
+ start_date. (Default: 31 Dec).
+
+ Properties:
+ * start_date
+ * end_date
+ * day_count
+ """
+ __slots__=('_start_date','_end_date')
+
+ def__init__(self,start_date=Date(1,1),end_date=Date(12,31)):
+"""Initialize UWGRunPeriod."""
+ # process the dates
+ ifstart_dateisnotNone:
+ self._check_date(start_date,'start_date')
+ self._start_date=start_date
+ else:
+ self._start_date=Date(1,1)
+ self.end_date=end_date
+
+ @property
+ defstart_date(self):
+"""Get or set a ladybug Date object for the start of the simulation period."""
+ returnself._start_date
+
+ @start_date.setter
+ defstart_date(self,value):
+ ifvalueisnotNone:
+ self._check_date(value,'start_date')
+ self._start_date=value
+ else:
+ self._start_date=Date(1,1)
+ self._check_start_before_end()
+
+ @property
+ defend_date(self):
+"""Get or set a ladybug Date object for the end of the simulation period."""
+ returnself._end_date
+
+ @end_date.setter
+ defend_date(self,value):
+ ifvalueisnotNone:
+ self._check_date(value,'end_date')
+ self._end_date=value
+ else:
+ self._end_date=Date(12,31)
+ self._check_start_before_end()
+
+ @property
+ defday_count(self):
+"""Get an integer for the number of days in the run period."""
+ returnint(self.end_date.doy-self.start_date.doy+1)
+
+
+[docs]
+ @classmethod
+ deffrom_analysis_period(cls,analysis_period=AnalysisPeriod(1,1,0,12,31,23)):
+"""Initialize a UWGRunPeriod object from a ladybug AnalysisPeriod.
+
+ Args:
+ analysis_period: A ladybug AnalysisPeriod object that has the start
+ and end dates for daylight savings time.
+ """
+ assertisinstance(analysis_period,AnalysisPeriod),'Expected AnalysisPeriod ' \
+ 'for UWGRunPeriod.from_analysis_period. Got {}.'.format(
+ type(analysis_period))
+ st_date=Date(analysis_period.st_month,analysis_period.st_day,
+ analysis_period.is_leap_year)
+ end_date=Date(analysis_period.end_month,analysis_period.end_day,
+ analysis_period.is_leap_year)
+ returncls(st_date,end_date)
+
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a UWGRunPeriod object from a dictionary.
+
+ Args:
+ data: A UWGRunPeriod dictionary in following the format below.
+
+ .. code-block:: python
+
+ {
+ "type": "UWGRunPeriod",
+ "start_date": [3, 12],
+ "end_date": [11, 5]
+ }
+ """
+ assertdata['type']=='UWGRunPeriod', \
+ 'Expected UWGRunPeriod dictionary. Got {}.'.format(data['type'])
+ start_date=Date.from_array(data['start_date'])if'start_date'indataand \
+ data['start_date']isnotNoneelseDate(1,1)
+ end_date=Date.from_array(data['end_date'])if'end_date'indataand \
+ data['end_date']isnotNoneelseDate(12,31)
+ returncls(start_date,end_date)
+[docs]
+ defduplicate(self):
+"""Get a copy of this object."""
+ returnself.__copy__()
+
+
+ def_check_start_before_end(self):
+"""Check that the start_date is before the end_date."""
+ assertself.start_date.leap_yearisself.end_date.leap_year, \
+ 'UWGRunPeriod start_date.leap_year must match the end_date.leap_year'
+ assertself._start_date<=self._end_date,'UWGRunPeriod start_date must ' \
+ 'be before end_date. {} is after {}.'.format(self.start_date,self.end_date)
+
+ @staticmethod
+ def_check_date(date,date_name='date'):
+ assertisinstance(date,Date),'Expected ladybug Date for ' \
+ 'UWGRunPeriod {}. Got {}.'.format(date_name,type(date))
+
+
+[docs]
+classVegetationParameter(object):
+"""Represents the behavior of vegetation within an urban area.
+
+ Args:
+ vegetation_albedo: A number between 0 and 1 that represents
+ the ratio of reflected radiation from vegetated surfaces
+ to incident radiation upon them. (Default: 0.25)
+ start_month: An integer from 1 to 12 that represents the month
+ at which vegetation evapostranspiration begins (leaves come out).
+ If Autocalculate, the month will be automatically determined by analyzing
+ the epw to see which months have an average monthly temperature
+ above 10C. (Default: autocalculate).
+ end_month: An integer from 1 to 12 that represents the month
+ at which vegetation evapostranspiration ends (leaves fall off).
+ If Autocalculate, the month will be automatically determined by analyzing
+ the epw to see which months have an average monthly temperature
+ above 10C. (Default: autocalculate).
+ 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. (Default: 0.7).
+ 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. (Default: 0.5).
+ """
+
+ __slots__=('_vegetation_albedo','_start_month','_end_month',
+ '_tree_latent_fraction','_grass_latent_fraction')
+
+ def__init__(self,vegetation_albedo=0.25,start_month=autocalculate,
+ end_month=autocalculate,
+ tree_latent_fraction=0.7,grass_latent_fraction=0.5):
+"""Initialize dragonfly vegetation parameters"""
+ self.vegetation_albedo=vegetation_albedo
+ self.start_month=start_month
+ self.end_month=end_month
+ self.tree_latent_fraction=tree_latent_fraction
+ self.grass_latent_fraction=grass_latent_fraction
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a VegetationParameter object from a dictionary
+
+ Args:
+ data: A dictionary representation of an VegetationParameter object
+ in the format below.
+
+ .. code-block:: python
+
+ {
+ 'type': 'VegetationParameter',
+ 'vegetation_albedo': 0.3, # float between 0 and 1
+ 'start_month': 5, # int between 1 and 12
+ 'end_month': 10, # int between 1 and 12
+ 'tree_latent_fraction': 0.75, # float between 0 and 1
+ 'grass_latent_fraction': 0.45 # float between 0 and 1
+ }
+ """
+ alb=data['vegetation_albedo']if'vegetation_albedo'indataelse0.25
+ start=autocalculateif'start_month'notindataor \
+ data['start_month']==autocalculate.to_dict()elsedata['start_month']
+ end=autocalculateif'end_month'notindataor \
+ data['end_month']==autocalculate.to_dict()elsedata['end_month']
+ tree=data['tree_latent_fraction']if'tree_latent_fraction'indataelse0.7
+ grass=data['grass_latent_fraction']if'grass_latent_fraction'indataelse0.5
+ returncls(alb,start,end,tree,grass)
+
+
+ @property
+ defvegetation_albedo(self):
+"""Get or set a fractional number for the vegetation albedo."""
+ returnself._vegetation_albedo
+
+ @vegetation_albedo.setter
+ defvegetation_albedo(self,value):
+ self._vegetation_albedo=float_in_range(value,0,1,'vegetation_albedo')
+
+ @property
+ defstart_month(self):
+"""Get or set an integer (or Autocalculate) for the vegetation start month."""
+ returnself._start_monthifself._start_monthisnotNoneelseautocalculate
+
+ @start_month.setter
+ defstart_month(self,value):
+ ifvalue==autocalculate:
+ self._start_month=None
+ else:
+ self._start_month= \
+ int_in_range(value,1,12,'start_month')
+
+ @property
+ defend_month(self):
+"""Get or set an integer (or Autocalculate) for the vegetation end month."""
+ returnself._end_monthifself._end_monthisnotNone \
+ elseautocalculate
+
+ @end_month.setter
+ defend_month(self,value):
+ ifvalue==autocalculate:
+ self._end_month=None
+ else:
+ self._end_month= \
+ int_in_range(value,1,12,'end_month')
+
+ @property
+ deftree_latent_fraction(self):
+"""Get or set a number for the tree latent fraction."""
+ returnself._tree_latent_fraction
+
+ @tree_latent_fraction.setter
+ deftree_latent_fraction(self,value):
+ self._tree_latent_fraction=float_in_range(value,0,1,'tree_latent_fraction')
+
+ @property
+ defgrass_latent_fraction(self):
+"""Get or set a number for the grass latent fraction."""
+ returnself._grass_latent_fraction
+
+ @grass_latent_fraction.setter
+ defgrass_latent_fraction(self,value):
+ self._grass_latent_fraction= \
+ float_in_range(value,0,1,'grass_latent_fraction')
+
+
+[docs]
+classTerrain(object):
+"""Object representing the terrain on which an urban area sits.
+
+ Note:
+ [1] 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
+
+ Args:
+ geometry: An array of ladybug_geometry Face3D objects that together
+ represent the terrain. This should include the entire area of the
+ site, including that beneath building footprints.
+ pavement_albedo: A number between 0 and 1 that represents the albedo
+ (reflectivity) of the pavement. (Default: 0.1, typical of fresh asphalt).
+ pavement_thickness: A number that represents the thickness of the
+ pavement material in meters. (Default: 0.5 meters).
+ pavement_conductivity: A number representing the conductivity of the pavement
+ material in W/m-K. (Default: 1 W/m-K, typical of asphalt).
+ pavement_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. (Default: 1.6e6 J/m3-K, typical of asphalt).
+
+ Properties:
+ * geometry
+ * pavement_albedo
+ * pavement_thickness
+ * pavement_conductivity
+ * pavement_heat_capacity
+ * polygon2ds
+ * area
+ * horizontal_area
+ * characteristic_length
+ * min
+ * max
+ """
+ __slots__=('_geometry','_polygon2ds','_pavement_albedo','_pavement_thickness',
+ '_pavement_conductivity','_pavement_heat_capacity')
+
+ def__init__(self,geometry,pavement_albedo=0.1,pavement_thickness=0.5,
+ pavement_conductivity=1.0,pavement_heat_capacity=1.6e6):
+"""Initialize a dragonfly Terrain"""
+ # process the geometry
+ ifnotisinstance(geometry,tuple):
+ geometry=tuple(geometry)
+ assertlen(geometry)>0,'Terrain must have at least one Face3D.'
+ forgeoingeometry:
+ assertisinstance(geo,Face3D), \
+ 'Expected ladybug_geometry Face3D. Got {}'.format(type(geo))
+ self._geometry=geometry
+ self._polygon2ds=None
+
+ # process the other parameters
+ self.pavement_albedo=pavement_albedo
+ self.pavement_thickness=pavement_thickness
+ self.pavement_conductivity=pavement_conductivity
+ self.pavement_heat_capacity=pavement_heat_capacity
+
+
+[docs]
+ @classmethod
+ deffrom_building_bounding_rect(cls,buildings):
+"""Initialize a Terrain from a list of dragonfly Buildings.
+
+ Args:
+ buildings: An array of dragonfly Buildings around which a bounding
+ rectangle will be computed to produce terrain geometry.
+ """
+ # figure out the min and max Point2D around all of the geometry
+ min_pt,max_pt=buildings[0].min,buildings[0].max
+ min_pt,max_pt=[min_pt.x,min_pt.y],[max_pt.x,max_pt.y]
+ forbldginbuildings[1:]:
+ bldg_min,bldg_max=bldg.min,bldg.max
+ ifbldg_min.x<min_pt[0]:
+ min_pt[0]=bldg_min.x
+ ifbldg_min.y<min_pt[1]:
+ min_pt[1]=bldg_min.y
+ ifbldg_max.x>max_pt[0]:
+ max_pt[0]=bldg_max.x
+ ifbldg_max.y>max_pt[1]:
+ max_pt[1]=bldg_max.y
+ # convert the min and max into a Face3D
+ base,height=max_pt[0]-min_pt[0],max_pt[1]-min_pt[1]
+ base_plane=Plane(o=Point3D(min_pt[0],min_pt[1],0))
+ returncls((Face3D.from_rectangle(base,height,base_plane),))
+
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Initialize a Terrain from a dictionary.
+
+ Args:
+ data: A dictionary representation of a Terrain object in the format below.
+
+ .. code-block:: python
+
+ {
+ "type": 'Terrain',
+ "geometry": [], # array for Face3D for the terrain surface
+ "pavement_albedo": 0.15, # number for the pavement albedo
+ "pavement_thickness": 0.75, # pavement thickness in meters
+ "pavement_conductivity": 1.0, # pavement conductivity in W/m2-K
+ "pavement_heat_capacity": 1600000 # volumetric heat capacity in J/m3-K
+ }
+ """
+ # check the type of dictionary
+ assertdata['type']=='Terrain','Expected Terrain dictionary. ' \
+ 'Got {}.'.format(data['type'])
+ # process the geometry
+ geometry=tuple(Face3D.from_dict(geo)forgeoindata['geometry'])
+ # process the other parameters
+ alb=data['pavement_albedo']if'pavement_albedo'indataelse0.1
+ thick=data['pavement_thickness']if'pavement_thickness'indataelse0.5
+ cond=data['pavement_conductivity']if'pavement_conductivity'indataelse1.0
+ h_cap=data['pavement_heat_capacity'] \
+ if'pavement_heat_capacity'indataelse1.6e6
+ returncls(geometry,alb,thick,cond,h_cap)
+
+
+ @property
+ defgeometry(self):
+"""Get a tuple of Face3D objects that together represent the Terrain."""
+ returnself._geometry
+
+ @property
+ defpavement_albedo(self):
+"""Get or set a number between 0 and 1 for the pavement albedo (reflectivity)."""
+ returnself._pavement_albedo
+
+ @pavement_albedo.setter
+ defpavement_albedo(self,value):
+ self._pavement_albedo=float_in_range(value,0,1,'pavement_albedo')
+
+ @property
+ defpavement_thickness(self):
+"""Get or set a number for the pavement thickness in meters."""
+ returnself._pavement_thickness
+
+ @pavement_thickness.setter
+ defpavement_thickness(self,value):
+ self._pavement_thickness=float_positive(value,'pavement_thickness')
+
+ @property
+ defpavement_conductivity(self):
+"""Get or set a number for the pavement conductivity in W/m-K."""
+ returnself._pavement_conductivity
+
+ @pavement_conductivity.setter
+ defpavement_conductivity(self,value):
+ self._pavement_conductivity=float_positive(value,'pavement_conductivity')
+
+ @property
+ defpavement_heat_capacity(self):
+"""Get or set a number for the pavement volumetric heat capacity in J/m3-K."""
+ returnself._pavement_heat_capacity
+
+ @pavement_heat_capacity.setter
+ defpavement_heat_capacity(self,value):
+ self._pavement_heat_capacity=float_positive(value,'pavement_heat_capacity')
+
+ @property
+ defpolygon2ds(self):
+"""Get a tuple of Polygon2D objects that together represent the Terrain."""
+ ifself._polygon2dsisNone:
+ self._polygon2ds=self._face3d_to_polygon2d(self._geometry)
+ returnself._polygon2ds
+
+ @property
+ defarea(self):
+"""Get a number for the total surface area of the Terrain."""
+ returnsum([geo.areaforgeoinself._geometry])
+
+ @property
+ defhorizontal_area(self):
+"""Get a number for the horizontal area of the urban Terrain surface.
+
+ This is projected into the XY plane.
+ """
+ returnsum([geo.areaforgeoinself.polygon2ds])
+
+ @property
+ defcharacteristic_length(self):
+"""Get a number for the characteristic length.
+
+ This is the linear dimension of the side of a square that encompasses
+ the neighborhood.
+ """
+ returnmath.sqrt(self.horizontal_area)
+
+ @property
+ defmin(self):
+"""Get a Point2D for the min bounding rectangle vertex in the XY plane."""
+ returnself._calculate_min(self._geometry)
+
+ @property
+ defmax(self):
+"""Get a Point2D for the max bounding rectangle vertex in the XY plane."""
+ returnself._calculate_max(self._geometry)
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Move this Terrain along a vector.
+
+ Args:
+ moving_vec: A ladybug_geometry Vector3D with the direction and distance
+ to move the object.
+ """
+ self._geometry=tuple(geo.move(moving_vec)forgeoinself._geometry)
+ self._polygon2ds=None
+
+
+
+[docs]
+ defrotate_xy(self,angle,origin):
+"""Rotate this Terrain counterclockwise in the XY plane by a certain angle.
+
+ Args:
+ angle: An angle in degrees.
+ origin: A ladybug_geometry Point3D for the origin around which the
+ object will be rotated.
+ """
+ self._geometry=tuple(geo.rotate_xy(math.radians(angle),origin)
+ forgeoinself._geometry)
+ self._polygon2ds=None
+
+
+
+[docs]
+ defreflect(self,plane):
+"""Reflect this Terrain across a plane.
+
+ Args:
+ plane: A ladybug_geometry Plane across which the object will be reflected.
+ """
+ self._geometry=tuple(geo.reflect(plane.n,plane.o)
+ forgeoinself._geometry)
+ self._polygon2ds=None
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale this Terrain by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the object should be scaled.
+ origin: A ladybug_geometry Point3D representing the origin from which
+ to scale. If None, it will be scaled from the World origin (0, 0, 0).
+ """
+ self._geometry=tuple(geo.scale(factor,origin)
+ forgeoinself._geometry)
+ self._polygon2ds=None
+
+
+
+[docs]
+ defduplicate(self):
+"""Get a copy of this object."""
+ returnself.__copy__()
+
+
+ @staticmethod
+ def_face3d_to_polygon2d(geometry):
+"""Convert a list of Face3D into Polygon2D in the XY Plane."""
+ vert2ds=((Point2D(pt.x,pt.y)forptinpoly)forpolyingeometry)
+ returntuple(Polygon2D(poly)forpolyinvert2ds)
+
+ @staticmethod
+ def_calculate_min(geometry_objects):
+"""Calculate min Point2D around an array of geometry with min attributes.
+
+ This is used in all functions that calculate bounding rectangles around
+ dragonfly objects and assess when two objects are in close proximity.
+ """
+ min_pt=[geometry_objects[0].min.x,geometry_objects[0].min.y]
+
+ forroomingeometry_objects[1:]:
+ ifroom.min.x<min_pt[0]:
+ min_pt[0]=room.min.x
+ ifroom.min.y<min_pt[1]:
+ min_pt[1]=room.min.y
+
+ returnPoint2D(min_pt[0],min_pt[1])
+
+ @staticmethod
+ def_calculate_max(geometry_objects):
+"""Calculate max Point2D around an array of geometry with max attributes.
+
+ This is used in all functions that calculate bounding rectangles around
+ dragonfly objects and assess when two objects are in close proximity.
+ """
+ max_pt=[geometry_objects[0].max.x,geometry_objects[0].max.y]
+
+ forroomingeometry_objects[1:]:
+ ifroom.max.x>max_pt[0]:
+ max_pt[0]=room.max.x
+ ifroom.max.y>max_pt[1]:
+ max_pt[1]=room.max.y
+
+ returnPoint2D(max_pt[0],max_pt[1])
+
+ def__copy__(self):
+ new_obj=Terrain(self._geometry)
+ new_obj._polygon2ds=self._polygon2ds
+ new_obj._pavement_albedo=self._pavement_albedo
+ new_obj._pavement_thickness=self._pavement_thickness
+ new_obj._pavement_conductivity=self._pavement_conductivity
+ new_obj._pavement_heat_capacity=self._pavement_heat_capacity
+ returnnew_obj
+
+
+[docs]
+classTrafficParameter(object):
+"""Object representing the traffic within an urban area.
+
+ Note:
+ [1] Sailor, David J. (2011). A review of methods for estimating anthropogenic
+ heat and moisture emissions in the urban environment. Royal Meteorological
+ Society, Volume 31, Issue 2, Pages 189-199. https://doi.org/10.1002/joc.2106
+
+ Args:
+ watts_per_area: A number representing the maximum sensible anthropogenic heat
+ flux of the urban area in watts per square meter. This is specifically the
+ heat that DOES NOT originate from buildings and mostly includes heat
+ from automobiles, street lighting, and human metabolism. If autocalculate,
+ it will be estimated frm the average building story count of the model
+ hosting the traffic parameters (Default: autocalculate). Values
+ for different cities can be found in (Sailor, 2011)[1]. Typical
+ values include:
+
+ * 20 W/m2 = A typical downtown area
+ * 10 W/m2 = A commercial area in Singapore
+ * 8 W/m2 = A typical mixed use part of Toulouse, France
+ * 4 W/m2 = A residential area in Singapore
+
+ weekday_schedule: A list of 24 fractional values that will be
+ multiplied by the watts_per_area to produce hourly values for
+ heat on the weekday of the simulation. (Default: a typical schedule
+ for a commercial area).
+ saturday_schedule: A list of 24 fractional values that will be
+ multiplied by the watts_per_area to produce hourly values for
+ heat on the Saturday of the simulation. (Default: a typical schedule
+ for a commercial area).
+ sunday_schedule: A list of 24 fractional values that will be
+ multiplied by the watts_per_area to produce hourly values for
+ heat on the Sunday of the simulation. (Default: a typical schedule
+ for a commercial area).
+ """
+ __slots__=('_watts_per_area','_weekday_schedule','_saturday_schedule',
+ '_sunday_schedule')
+
+ WEEKDAY_DEFAULT= \
+ (0.2,0.2,0.2,0.2,0.2,0.4,0.7,0.9,0.9,0.6,0.6,0.6,
+ 0.6,0.6,0.7,0.8,0.9,0.9,0.8,0.8,0.7,0.3,0.2,0.2)
+ SATURDAY_DEFAULT= \
+ (0.2,0.2,0.2,0.2,0.2,0.3,0.5,0.5,0.5,0.5,0.5,0.5,
+ 0.5,0.5,0.6,0.7,0.7,0.7,0.7,0.5,0.4,0.3,0.2,0.2)
+ SUNDAY_DEFAULT= \
+ (0.2,0.2,0.2,0.2,0.2,0.3,0.4,0.4,0.4,0.4,0.4,0.4,
+ 0.4,0.4,0.4,0.4,0.4,0.4,0.4,0.4,0.3,0.3,0.2,0.2)
+
+ def__init__(self,watts_per_area=autocalculate,weekday_schedule=None,
+ saturday_schedule=None,sunday_schedule=None):
+"""Initialize dragonfly traffic parameters"""
+ self.watts_per_area=watts_per_area
+ self.weekday_schedule=weekday_schedule
+ self.saturday_schedule=saturday_schedule
+ self.sunday_schedule=sunday_schedule
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Initialize an TrafficParameter from a dictionary.
+
+ Args:
+ data: A dictionary representation of an TrafficParameter object
+ in the format below.
+
+ .. code-block:: python
+
+ {
+ "type": 'TrafficParameter',
+ "watts_per_area": 10, # number for heat in W/m2
+ "weekday_schedule": [], # list of 24 fractional values for a schedule
+ "saturday_schedule": [], # list of 24 fractional values for a schedule
+ "sunday_schedule": [] # list of 24 fractional values for a schedule
+ }
+ """
+ watts=autocalculateif'watts_per_area'notindataor \
+ data['watts_per_area']==autocalculate.to_dict()elsedata['watts_per_area']
+ weekday=data['weekday_schedule']if'weekday_schedule'indataelseNone
+ saturday=data['saturday_schedule']if'saturday_schedule'indataelseNone
+ sunday=data['sunday_schedule']if'sunday_schedule'indataelseNone
+ returncls(watts,weekday,saturday,sunday)
+
+
+ @property
+ defwatts_per_area(self):
+"""Get or set a number for the max sensible heat flux of the traffic."""
+ returnself._watts_per_areaifself._watts_per_areaisnotNone \
+ elseautocalculate
+
+ @watts_per_area.setter
+ defwatts_per_area(self,value):
+ ifvalue==autocalculate:
+ self._watts_per_area=None
+ else:
+ self._watts_per_area=float_positive(value,'traffic watts per area')
+
+ @property
+ defweekday_schedule(self):
+"""Get or set the Weekday traffic schedule as a list of 24 fractional values."""
+ returnself._weekday_scheduleifself._weekday_scheduleisnotNone \
+ elseself.WEEKDAY_DEFAULT
+
+ @weekday_schedule.setter
+ defweekday_schedule(self,value):
+ self._weekday_schedule=self._check_schedule(value) \
+ ifvalueisnotNoneelseNone
+
+ @property
+ defsaturday_schedule(self):
+"""Get or set the Saturday traffic schedule as a list of 24 fractional values."""
+ returnself._saturday_scheduleifself._saturday_scheduleisnotNone \
+ elseself.SATURDAY_DEFAULT
+
+ @saturday_schedule.setter
+ defsaturday_schedule(self,value):
+ self._saturday_schedule=self._check_schedule(value) \
+ ifvalueisnotNoneelseNone
+
+ @property
+ defsunday_schedule(self):
+"""Get or set the Sunday traffic schedule as a list of 24 fractional values."""
+ returnself._sunday_scheduleifself._sunday_scheduleisnotNone \
+ elseself.SUNDAY_DEFAULT
+
+ @sunday_schedule.setter
+ defsunday_schedule(self,value):
+ self._sunday_schedule=self._check_schedule(value) \
+ ifvalueisnotNoneelseNone
+
+
+[docs]
+ defduplicate(self):
+"""Get a copy of this object."""
+ returnself.__copy__()
+"""Methods to write files for UWG simulation from a Model."""
+from.simulation.parameterimportUWGSimulationParameter
+
+
+
+[docs]
+defmodel_to_uwg(model,epw_file,simulation_parameter=None):
+"""Create a fully simulate-able uwg dictionary from a Model.
+
+ Args:
+ model: A dragonfly Model for which an URBANopt feature geoJSON and corresponding
+ honeybee Model JSONs will be returned.
+ epw_file: File path to the EPW that will be morphed by the UWG. This will be
+ used to fill all autocalculated fields like the ASHRAE climate zone
+ and vegetation start/end.
+ simulation_parameter: A UWGSimulationParameter object that dictates various
+ settings about the UWG simulation. If None, default parameters will
+ be generated. (Default: None).
+
+ Returns:
+ A dictionary following the UWG schema. This dictionary can be serialized
+ into a JSON in order to be run through the UWG.
+ """
+ # get the base dictionary from the model; independent of simulation parameters
+ ifmodel.units!='Meters':
+ model=model.duplicate()# duplicate the model to avoid mutating the input
+ model.convert_to_units('Meters')
+ uwg_dict=model.properties.uwg.to_uwg_dict()
+
+ # get a dictionary for the simulation parameters and update the base
+ sim_par=simulation_parameterifsimulation_parameterisnotNone \
+ elseUWGSimulationParameter()
+ sim_par_dict=sim_par.to_uwg_dict(epw_file)
+ uwg_dict.update(sim_par_dict)
+
+ # get the average SHGC across the buildings using the climate zone
+ uwg_dict['shgc']=model.properties.uwg.average_shgc(uwg_dict['zone'])
+
+ # add other properties that have not been exposed elsewhere in the SDK
+ uwg_dict['dtweather']=3600
+ uwg_dict['autosize']=False
+ uwg_dict['sensocc']=100
+ uwg_dict['latfocc']=0.3
+ uwg_dict['radfocc']=0.2
+ uwg_dict['radfequip']=0.5
+ uwg_dict['radflight']=0.7
+ uwg_dict['maxday']=150
+ uwg_dict['maxnight']=20
+ uwg_dict['windmin']=1
+ returnuwg_dict