Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Morph a rural or airport EPW to reflect the conditions within an urban street canyon. The properties of this urban street canyon are specified in the connected _model.
For definitions of the inputs of the Urban Weather Generator, please see the UWG schema documentation (https://www.ladybug.tools/uwg-schema/index.html).
For a full list of publications on the Urban Weather Generator, see the MIT Urban Microclimate Group (http://urbanmicroclimate.scripts.mit.edu/publications.php).
model [Required]
A Dragonfly Model to be used to morph the EPW for the urban area.
epw_file [Required]
Full path to an .epw file. This is the rural or airport file that will be morphed to reflect the climate conditions within an urban canyon.
sim_par
A dragonfly UWG SimulationParameter object that describes all of the setting for the simulation. If None, some default simulation parameters will be used.
folder
File path for the directory into which the the uwg JSON and morphed urban EPW will be written. If None, it will be written into the ladybug default_epw_folder within a subfolder bearing the name of the dragonfly Model.
write [Required]
Set to "True" to generate a UWG JSON from the connected _model and parameters. This JSON can be edited and simulated by the UWG directly.
run
Set to "True" to simulate the uwg_json with the Urban Weather Generator (UWG) and morph the input EPW to account for urban heat island. This can also be the integer "2", which will run the UWG silently (without any batch windows).
report
Reports, errors, warnings, etc.
uwg_json
Path to a fully-simulatable JSON file following the UWG schema. This contains all of the relevant Dragonfly Model properties and input parameters.
urban_epw
Path to the morphed EPW file output from the UWG, which represents urban heat island conditions within the street canyon.
Edit the properties of a Dragonfly Model that affect simulation with to the Urban Weather Generator (UWG).
model [Required]
A Dragonfly Model which is to have its Urban Weather Generator (UWG) properties assigned.
terrain
A Terrain object that dictates the properties of the street and ground beneath the buildings. If None, a default terrain object will be generated by analysing all of the buildings in the Model and drawing a bounding rectangle in the XY plane around them.
traffic
A TrafficPararameter object that defines the activity and intensity of traffic within the urban street canyons. If None, traffic intensity will be approximated using the average building story count along with a generic traffic schedule.
tree_cover
A number from 0 to 1 that defines the fraction of the exposed terrain covered by trees. If None, it will be determined by evaluating the horizontal area of all ContextShade geometry that has a true is_vegetation property.
grass_cover
A number from 0 to 1 that defines the fraction of the exposed terrain that is covered by grass or shrubs. If None, no grass will be assumed for the urban area.
report
...
model
The input Dragonfly Model with its UWG properties re-assigned based on the input.
Create a simulation parameter object that carries a complete set of Urban Weather Genreator (UWG) simulation settings and can be plugged into the "DF Run Urban Weather Generator" component.
run_period
A Ladybug Analysis Period object to describe the time period over which to run the simulation. If None, the simulation will be run for the whole year.
timestep
An integer for the number of timesteps per hour at which the calculation will be run. (Default: 12).
veg_par
A VegetationParameter object to specify the behavior of vegetation in the urban area. If None, generic vegetation parameters will be generated.
epw_site
A ReferenceEPWSite object to specify the properties of the reference site where the input rural EPW was recorded. If None, generic airport properties will be generated.
bnd_layer
A BoundaryLayerParameter to specify the properties of the urban boundary layer. If None, generic boundary layer parameters will be generated.
sim_par
A UWG SimulationParameter object that can be connected to the "DF Run Urban Weather Generator" component in order to specify UWG simulation settings
Edit the properties of a Dragonfly Building that affect simulation with to the Urban Weather Generator (UWG).
building [Required]
A Dragonfly Building which is to have its Urban Weather Generator (UWG) properties assigned.
program
Text for the name of the building program. Must be one of the options below. (Default: LargeOffice).
LargeOffice
MediumOffice
SmallOffice
MidriseApartment
Retail
StripMall
PrimarySchool
SecondarySchool
SmallHotel
LargeHotel
Hospital
Outpatient
Warehouse
SuperMarket
FullServiceRestaurant
QuickServiceRestaurant
vintage
Text for the vintage of the building. This will be used to set default constructions. Must be one of the options below or one of the options from the "HB Building Vintages" component, which will be mapped to one of the options below. (Default: New).
New
1980_Present
Pre1980
fr_canyon
A number from 0 to 1 that represents the fraction of the building's waste heat from air conditioning that gets rejected into the urban canyon. (Default: 0.5).
shgc
A number from 0 to 1 that represents the SHGC of the building's windows. This is used to evaluate the amount of solar heat reflected into the street canyon. By default, it will be set by the building vintage and the Model climate zone.
wall_alb
A number from 0 to 1 that represents the exterior wall albedo of the building. By default, it will be set by the building program and the DoE commercial reference buildings.
roof_alb
A number from 0 to 1 that represents the exterior roof albedo of the building. By default, it will be set by the vintage, meaning 0.7 for New and 0.2 for 1980_Present and Pre1980.
roof_veg
A number from 0 to 1 that represents the fraction of the building's roofs covered in vegetation. (Default: 0).
report
...
building
The input Dragonfly Building with its UWG properties re-assigned based on the input.
Create a Terrain object representing the land on which an urban area sits.
This includes both the geometry and the properties of the pavement within the urban area.
terrain_geo [Required]
An array of Breps or meshes that together represent the terrian. This should include the entire area of the site, including that beneath building footprints.
albedo
A number between 0 and 1 that represents the albedo (reflectivity) of the pavement. (Default: 0.1, typical of fresh asphalt).
thickness
A number that represents the thickness of the pavement material in meters. (Default: 0.5 meters).
conductivity
A number representing the conductivity of the pavement material in W/m-K. (Default: 1 W/m-K, typical of asphalt).
vol_heat_cap
A number representing the volumetric heat capacity of the pavement material in J/m3-K. This is the number of joules needed to raise one cubic meter of the material by 1 degree Kelvin. (Default: 1.6e6 J/m3-K, typical of asphalt).
terrain
A Terrain object that can be plugged into the "DF Assign Model UWG Properties" component to specify the terrain of an urban area.
Create TrafficParameters representing the traffic within an urban area.
watts_per_area [Required]
A number representing the maximum sensible anthropogenic heat flux of the urban area in watts per square meter. This is specifcally the heat that DOES NOT originate from buildings and mostly includes heat from automobiles, street lighting, and human metabolism. If autocalculate, it will be estimated frm the average building story count of the model hosting the traffic parameters (Default: autocalculate). Values for different cities can be found in (Sailor, 2011)[1]. Typical values include:
20 W/m2 = A typical downtown area
10 W/m2 = A commercial area in Singapore
8 W/m2 = A typical mixed use part of Toulouse, France
4 W/m2 = A residential area in Singapore
weekday_sch
A list of 24 fractional values that will be multiplied by the watts_per_area to produce hourly values for heat on the weekday of the simulation. (Default: a typical schedule for a commercial area).
saturday_sch
A list of 24 fractional values that will be multiplied by the watts_per_area to produce hourly values for heat on the Saturday of the simulation. (Default: a typical schedule for a commercial area).
sunday_sch
A list of 24 fractional values that will be multiplied by the watts_per_area to produce hourly values for heat on the Sunday of the simulation. (Default: a typical schedule for a commercial area).
traffic
Traffic parameters that can be plugged into the "DF Assign Model UWG Properties" component to specify the behavior of traffic within an urban area.
Write Ladybug DesignDays to a standard .ddy file.
location [Required]
A Ladybug Location object describing the location data in the weather file.
design_days [Required]
A list of DesignDay objects representing the design days contained within the ddy file.
folder
An optional folder to save the .ddy file.
name
An optional name for this .ddy file.
run [Required]
Set to "True" to run the component and write the .ddy file.
ddy_file
A .ddy file path that has been written to your system.
Construct a design day from a set of parameters.
name [Required]
The name of the DesignDay object.
day_type [Required]
Text indicating the type of design day (ie. 'SummerDesignDay', 'WinterDesignDay' or other EnergyPlus days).
location [Required]
A Ladybug Location object describing the location of the design day.
date [Required]
A Ladybug Date for the day of the year on which the design day occurs. This should be in the format of 'DD Month' (eg. '1 Jan', '4 Jul'). The LB Calculate HOY component can also be used to construct this date.
dry_bulb_max [Required]
Maximum dry bulb temperature over the design day (in C).
dry_bulb_range
Dry bulb range over the design day (in C).
humidity_type [Required]
Type of humidity to use. (ie. Wetbulb, Dewpoint, HumidityRatio, Enthalpy)
humidity_value [Required]
The value of the humidity condition above.
barometric_p
Barometric pressure in Pa.
wind_speed [Required]
Wind speed over the design day in m/s.
wind_dir [Required]
Wind direction over the design day in degrees.
sky_type [Required]
Type of solar model to use. (eg. ASHRAEClearSky, ASHRAETau)
sky_properties [Required]
A list of properties describing the sky above. For ASHRAEClearSky this is a single value for clearness. For ASHRAETau, this is the tau_beam and tau_diffuse.
design_day
Script output design_day.
-
Calculate downwelling horizontal infrared radiation intensity from sky cover, dry bulb temperature, and dew point temperature.
sky_cover [Required]
A value or data collection representing sky cover [tenths]
dry_bulb [Required]
A value or data collection representing dry bulb temperature [C]
dew_point [Required]
A value or data collection representing dew point temperature [C]
horiz_infrared
A data collection or value indicating the downwelling horizontal infrared radiation [W/m2]
-
Write an EPW object into a .epw file.
epw_obj [Required]
An EPW object such as that exported from the Create EPW component.
folder
A directory into which the .epw file will be written.
file_name
An optional name for the .epw file. Default will use the city of the EPW object's location.
run [Required]
Set to True to run the component and write the .epw file.
report
Reports, errors, warnings, etc.
epw_file
File path to a .epw that contains all of the data in the input _epw_obj.
-
Create a custom EPW object from a location and data collections of annual hourly data.
location [Required]
A location object for the epw_file.
dry_bulb_temp
Annual hourly data collection for dry bulb temperature [C]
dew_point_temp
Annual hourly data collection for dew point temperature [C]
wind_speed
Annual hourly data collection for wind speed [m/s]
wind_direction
Annual hourly data collection for wind direction [degrees]
direct_normal_rad
Annual hourly data collection for direct normal radiation [Wh/m2] or [W/m2]
diffuse_horiz_rad
Annual hourly data collection for diffuse horizontal radiation [Wh/m2] or [W/m2]
horiz_infrared_rad
Annual hourly data collection for horizontal infrared radiation intensity [Wh/m2] or [W/m2]
direct_normal_ill
Annual hourly data collection for direct normal illuminance [lux]
diffuse_horiz_ill
Annual hourly data collection for diffuse horizontal illuminance [lux]
total_sky_cover
Annual hourly data collection for the fraction for total sky cover [tenths]
atmos_pressure
Annual hourly data collection for weather station pressure [Pa]
visibility
Annual hourly data collection for visibility [km]
ceiling_height
Annual hourly data collection for cloud ceiling height [m]
model_year
Annual hourly data collection for the year from which the hourly data has been extracted. This input is necessary when the input data collections are from a leap year.
base_epw
File path to an optional .epw to fill empty slots for data that has not been connected here.
run [Required]
Set to True to run the component and create the epw_obj.
report
Reports, errors, warnings, etc.
epw_obj
An EPW object that can be written to a file using the Write EPW component.
-
Import climate data from a .csv file of annual data obtained from the National Oceanic and Atmospheric Administration (NOAA) database. The database can be accessed here:
noaa_file [Required]
The path to a .csv file of annual data obtained from the NOAA database on your system as a string.
time_zone
Optional time zone for the station. If blank, a default time zone will be estimated from the longitude.
timestep
Integer forthe timestep at which the data collections should be output. Data in the .csv that does not conform to this timestep will be ignored in the output data collections. This can be set as high as 60 to ensure that all data from the .csv file is imported. However, such large data collections can be time consuming to edit. (Default: 1).
run [Required]
Set to True to run the component and import the data.
location
Script variable ImportNOAA
dry_bulb_temp
The houlry dry bulb temperature, in C. Note that this is a full numeric field (i.e. 23.6) and not an integer representation with tenths. Valid values range from 70 C to 70 C. Missing value for this field is 99.9.
dew_point_temp
The hourly dew point temperature, in C. Note that this is a full numeric field (i.e. 23.6) and not an integer representation with tenths. Valid values range from 70 C to 70 C. Missing value for this field is 99.9.
wind_speed
The hourly wind speed in m/sec. Values can range from 0 to 40. Missing value is 999.
wind_direction
The hourly wind direction in degrees. The convention is that North=0.0, East=90.0, South=180.0, West=270.0. (If wind is calm for the given hour, the direction equals zero.) Values can range from 0 to 360. Missing value is 999.
total_sky_cover
The fraction for total sky cover (tenths of coverage). (i.e. 1 is 1/10 covered. 10 is total coverage) (Amount of sky dome in tenths covered by clouds or obscuring phenomena at the hour indicated at the time indicated.) Minimum value is 0; maximum value is 10; missing value is 99."
atmos_pressure
The hourly weather station pressure in Pa. Valid values range from 31,000 to 120,000... Missing value for this field is 999999."
visibility
This is the value for visibility in km. (Horizontal visibilitY). It is not currently used in EnergyPlus calculations. Missing value is 9999.
ceiling_height
Script output ceiling_height.
model_year
The year from which the hourly data has been extracted. Note that, for this component to run correclty, all of the data in the text file must be from a single year.
-
Create BoundaryLayerParameters representing the properties of the urban boundary layer in an Urban Weather Genrator (UWG) simulation.
day_hght
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_hght
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_hght
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).
circ_coeff
A number representing the circulation coefficient. (Default: 1.2, per Bueno (2012)).
exch_coeff
A number representing the exchange coefficient. (Default: 1.0, per Bueno (2014)).
bnd_layer
Boundary layer parameters that can be plugged into the "DF UWG Simulation Parameter" component to specify the properties of the urban boundary layer.
Create VegetationParameters representing the behavior of vegetation within an urban area.
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). By default, the month will be automatically determined by analyzing the epw to see which months have an average monthly temperature above 10C.
end_month
An integer from 1 to 12 that represents the month at which vegetation evapostranspiration ends (leaves fall off). By default, the month will be automatically determined by analyzing the epw to see which months have an average monthly temperature above 10C.
tree_latent
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
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).
veg_par
Vegetation parameters that can be plugged into the "DF UWG Simulation Parameter" component to specify the behavior of vegetation in the simulation.
Esimtate sky illuminance from the irradiance contained within a WEA object.
wea [Required]
A Ladybug WEA object.
dew_point [Required]
An annual data collection representing dew point temperature [C].
dir_ill
A data collection of direct normal illuminance values at each timestep of the WEA.
diff_ill
A list of diffuse sky solar illuminance values at each timestep of the WEA.
glob_ill
A list of global horizontal illuminance values at each timestep of the WEA.
-
Create Reference EPW Site parameters that represent the properties of the stie where rural EPW data was recorded for an Urban Weather Genrator (UWG) simulation.
obstacle_hght
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).
veg_cover
A number between 0 and 1 that represents the fraction of the reference EPW site that is covered in grass. (Default: 0.9).
temp_hght
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_hght
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).
epw_site
Reference EPW site parameters that can be plugged into the "DF UWG Simulation Parameter" component to specify the behavior of vegetation in the simulation.
