uwg.uwg module

Urban Weather Generator (UWG) Version 4.2

Original Author: B. Bueno[1] Edited by A. Nakano & Lingfu Zhang Modified by Joseph Yang (joeyang@mit.edu) - May, 2016 Translated to Python by Saeran Vasanthakumar - February, 2018

Note

[1] Bueno, Bruno; Norford, Leslie; Hidalgo, Julia; Pigeon, Gregoire (2012a). The urban weather generator, Journal of Building Performance Simulation. 6:4,269-281. doi: 10.1080/19401493.2012.718797

class uwg.uwg.UWG(epw_path=None, new_epw_dir=None, new_epw_name=None)[source]

Bases: object

Morph a rural EPW file to urban conditions based on defined urban parameters.

Parameters:

  • epw_path – Text string for full path of the rural .epw file that will be morphed. If set to None, other input parameters can be assigned but the UWG model cannot be generated from the inputs, which is useful in cases where a UWG model needs to be serialized but the file path structure is not known. (Default: None).

  • new_epw_dir – Optional text string for the destination directory into which the morphed .epw file is written. If None the morphed file will be written into the same directory as the rural .epw file. (Default: None).

  • new_epw_name – Optional text string for the destination file name of the morphed .epw file. If None the morphed file will append ‘_UWG’ to the original file name. (Default: None).

Properties:

  • epw_path – Full path of the rural .epw file that will be morphed.

  • new_epw_path – Full path of the file name of the morphed .epw file.

  • refBEM – Reference BEMDef matrix defined by built type, era, and zone.

  • refSchedule – Reference SchDef matrix defined by built type, era, and zone.

  • month – Number (1-12) representing simulation start month.

  • day – Number (1-31) representing simulation start day.

  • nday – Number of days to simulate.

  • dtsim – Simlation time step in seconds.

  • dtweather – Number for weather data time-step in seconds.

  • autosize – Boolean to set HVAC autosize.

  • sensocc – Sensible heat from occupant [W].

  • latfocc – Latent heat fraction from occupant.

  • radfocc – Radiant heat fraction from occupant.

  • radfequip – Radiant heat fraction from equipment.

  • radflight – Radiant heat fraction from electric light.

  • h_ubl1 – Daytime urban boundary layer height in meters.

  • h_ubl2 – Nighttime urban boundary layer height in meters.

  • h_ref – Inversion height in meters.

  • h_temp – Temperature height in meters.

  • h_wind – Wind height in meters.

  • c_circ – Wind scaling coefficient.

  • c_exch – Exchange velocity coefficient.

  • maxday – Maximum heat flux threshold for daytime conditions [W/m2].

  • maxnight – Maximum heat flux threshold for nighttime conditions [W/m2].

  • windmin – Minimum wind speed in m/s.

  • h_obs – Rural average obstacle height in meters.

  • bldheight – Urban building height in meters.

  • h_mix – Fraction of HVAC waste heat released to street canyon.

  • blddensity – Building footprint density as fraction of urban area.

  • vertohor – Vertical-to-horizontal urban area ratio.

  • charlength – Urban characteristic length in meters.

  • albroad – Urban road albedo.

  • droad – Thickness of urban road pavement thickness in meters.

  • sensanth – Street level anthropogenic sensible heat [W/m2].

  • zone – Index representing an ASHRAE climate zone.

  • grasscover – Fraction of urban ground covered in grass only.

  • treecover – Fraction of urban ground covered in trees.

  • vegstart – Month in which vegetation starts to evapotranspire.

  • vegend – Month in which vegetation stops evapotranspiration.

  • albveg – Vegetation albedo.

  • rurvegcover – Fraction of rural ground covered by vegetation.

  • latgrss – Fraction of latent heat absorbed by urban grass.

  • lattree – Fraction latent heat absorbed by urban trees.

  • schtraffic – Schedule of fractional anthropogenic heat load.

  • kroad – Road pavement conductivity [W/m-K].

  • croad – Road pavement volumetric heat capacity [J/m^3K].

  • bld – Matrix of numbers representing fraction of urban building stock.

  • albroof – Average building roof albedo.

  • vegroof – Fraction of roof covered in grass/shrubs.

  • glzr – Building glazing ratio.

  • albwall – Building albedo.

  • shgc – Building glazing Solar Heat Gain Coefficient (SHGC).

  • flr_h – Building floor height in meters.

  • ref_bem_vector – List of custom BEMDef objects to override the refBEM.

  • ref_sch_vector – List of custom SchDef objects to override the refSchedule.

ToString()[source]

Overwrite .NET ToString method.

classmethod from_dict(data, epw_path=None, new_epw_dir=None, new_epw_name=None)[source]

Create an UWG object from a dictionary.

Parameters:

  • data – An UWG dictionary following the format below. Note that this example has been truncated for the sake of brevity. For the full list of required properties in the UWG, see the initialization docstrings.

  • epw_path – Text string for full path of the rural .epw file that will be morphed. If set to None, other input parameters can be assigned but the UWG model cannot be generated from the inputs, which is useful in cases where a UWG model needs to be serialized but the file path structure is not known. (Default: None).

  • new_epw_dir – Optional text string for the destination directory into which the morphed .epw file is written. If None the morphed file will be written into the same directory as the rural .epw file. (Default: None).

  • new_epw_name – Optional text string for the destination file name of the morphed .epw file. If None the morphed file will append ‘_UWG’ to the original file name. (Default: None).

{
"type": "UWG",
"bldheight": 10,
"blddensity": 0.5,
"vertohor": 0.8,
...
"h_obs": 0.1,
"flr_h": 3.5,
"shgc": None,
# Optional vector of SchDef dictionary.
"ref_sch_vector": [sch.to_dict()]
# Optional vector of BEMDef dictionary.
"ref_bem_vector": [bem.to_dict()]
}
classmethod from_param_args(bldheight, blddensity, vertohor, grasscover, treecover, zone, month=1, day=1, nday=31, dtsim=300, dtweather=3600, bld=(('largeoffice', 'pst80', 0.4), ('midriseapartment', 'pst80', 0.6)), autosize=False, h_mix=1, sensocc=100, latfocc=0.3, radfocc=0.2, radfequip=0.5, radflight=0.7, charlength=1000, albroad=0.1, droad=0.5, kroad=1, croad=1600000, rurvegcover=0.9, vegstart=4, vegend=10, albveg=0.25, latgrss=0.4, lattree=0.6, sensanth=20, schtraffic=((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), (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), (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)), h_ubl1=1000, h_ubl2=80, h_ref=150, h_temp=2, h_wind=10, c_circ=1.2, c_exch=1, maxday=150, maxnight=20, windmin=1, h_obs=0.1, epw_path=None, new_epw_dir=None, new_epw_name=None, ref_bem_vector=None, ref_sch_vector=None)[source]

Create an UWG object based on default method arguments.

The default parameters are set from example parameters defined by Bueno et al. (2012a)[1] for Singapore. The original file can be accessed here: https://github.com/ladybug-tools/uwg/blob/master/resources/initialize_singapore.uwg.

Note

[1] Bueno, Bruno; Norford, Leslie; Hidalgo, Julia; Pigeon, Gregoire (2012a). The urban weather generator, Journal of Building Performance Simulation. 6:4, 269-281. doi: 10.1080/19401493.2012.718797

classmethod from_param_file(param_path, epw_path=None, new_epw_dir=None, new_epw_name=None)[source]

Create a UWG object from the .uwg parameter file.

Note: this method of initializing the UWG object doesn’t permit adding custom reference data.

Parameters:

  • param_path – Optional text string for full path of the the .uwg parameter file path.

  • epw_path – Text string for full path of the rural .epw file that will be morphed. If set to None, other input parameters can be assigned but the UWG model cannot be generated from the inputs, which is useful in cases where a UWG model needs to be serialized but the file path structure is not known. (Default: None).

  • new_epw_dir – Optional text string destination directory for the morphed .epw file. If None the morphed file will be written into the same directory as the rural .epw file. (Default: None).

  • new_epw_name – Optional destination file name for the morphed .epw file. If None the morphed file will append ‘_UWG’ to the original file name. (Default: None).

generate()[source]

Generate all UWG objects after input parameters are set.

static load_refDOE(refDOE_path='/home/runner/work/uwg/uwg/uwg/refdata/readDOE.pkl')[source]

Static method to deserialize DOE reference data.

Parameters:

  • readDOE_path – Text string for full path to the refDOE pickle.

  • (Default – the filepath specified in the UWG.REFDOE_PATH constant).

Returns:

Two 16 x 3 x 16 matrices of reference BEMDef and SchDef objects, respectively.

simulate()[source]

Simulate UWG object and produce urban canyon weather timeseries data.

This function will set the following attributes in the UWG object:

  • N - Total number of hours in simulation

  • ph - Number of simulation time steps per hour

  • dayType - Number representing day type: Sunday, Saturday or Weekday

  • ceil_time_step - sim timestep fitted to weather file timestep

  • solar - SolarCalcs object for current timestep solar calculation

  • WeatherData - N x 1 output vector of forc object instance

  • UCMData - N x 1 output vector of UCM object instance

  • UBLData - N x 1 output vector of UBL object instance

  • RSMData - N x 1 output vector of RSM object instace

  • USMData - N x 1 output vector of USM object instance

to_dict(include_refDOE=False)[source]

UWG dictionary representation.

Parameters:

add_refDOE – Optional boolean to include custom reference BEMDef and SchDef objects from the ref_bem_vector and ref_sch_vector attributes. (Default: False).

write_epw()[source]

Write new EPW file to new_epw_path property.

B = 9.4
CL = 4218.0
CM = 7.4
COLBURN = 1.096474711468775
CP = 1004.0
CPV = 1846.1
CURRENT_PATH = '/home/runner/work/uwg/uwg/uwg'
DEFAULT_BLD = (('largeoffice', 'pst80', 0.4), ('midriseapartment', 'pst80', 0.6))
DEFAULT_SCHTRAFFIC = ((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), (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), (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))
ESTT = 611.14
G = 9.81
LV = 2260000.0
LVTT = 2500800.0
MAXTHICKNESS = 0.05
MINTHICKNESS = 0.01
OPTIONAL_PARAMETER_SET = {'albroof', 'albwall', 'flr_h', 'glzr', 'shgc', 'vegroof'}
PARAMETER_LIST = ('month', 'day', 'nday', 'dtsim', 'dtweather', 'autosize', 'sensocc', 'latfocc', 'radfocc', 'radfequip', 'radflight', 'h_ubl1', 'h_ubl2', 'h_ref', 'h_temp', 'h_wind', 'c_circ', 'c_exch', 'maxday', 'maxnight', 'windmin', 'h_obs', 'bldheight', 'h_mix', 'blddensity', 'vertohor', 'charlength', 'albroad', 'droad', 'sensanth', 'zone', 'grasscover', 'treecover', 'vegstart', 'vegend', 'albveg', 'rurvegcover', 'latgrss', 'lattree', 'schtraffic', 'kroad', 'croad', 'bld', 'shgc', 'albroof', 'glzr', 'vegroof', 'albwall', 'flr_h')
R = 287.0
REFDOE_PATH = '/home/runner/work/uwg/uwg/uwg/refdata/readDOE.pkl'
RV = 461.5
SIGMA = 5.67e-08
SOIL = Material, name: soil  thermalcond: 1  volheat: 2000000.0
SOILTCOND = 1
SOILVOLHEAT = 2000000.0
TT = 273.16
VK = 0.4
WATERDENS = 1000.0
WGMAX = 0.005
Z_MESO_PATH = '/home/runner/work/uwg/uwg/uwg/refdata/z_meso.txt'
property albroad

Get or set urban road albedo.

property albroof

Get or set average building roof albedo.

If value is None, a unique albroof is set for each building from the refBEM. (Default: None).

property albveg

Get or set vegetation albedo.

property albwall

Get or set average building albedo.

If value is None, a unique albwall is set for each building from the refBEM. (Default: None).

property autosize

Get or set boolean to autosize HVAC system.

property bld

Get or set list of building types, eras, and fractions of urban building stock.

This property consists of a list of tuples, each containing a string for the the built era, and a number between 0 and 1, inclusive, defining built stock fraction, i.e (‘LargeOffice’, ‘New’, 0.4). The fractions should sum to one.

768 predefined models are built referencing 16 building types for 3 built eras and 16 climate zones according to models from the Department of Energy (DOE). Choose from the following text identifiers to reference a DOE building type:

  • ‘fullservicerestaurant’

  • ‘hospital’

  • ‘largehotel’

  • ‘largeoffice’

  • ‘medoffice’

  • ‘midriseapartment’

  • ‘outpatient’

  • ‘primaryschool’

  • ‘quickservicerestaurant’

  • ‘secondaryschool’

  • ‘smallhotel’

  • ‘smalloffice’

  • ‘standaloneretail’

  • ‘stripmall’

  • ‘supermarket’

  • ‘warehouse’

Choose from the following built eras:

  • ‘pre80’

  • ‘pst80’

  • ‘new’

Custom building types can also be referenced in this property. For example, a built stock consisting of 40% post-1980’s large office, 30% new midrise apartment, and 30% of a pre-1980s custom building type (defined by the user) is referenced as follows:

bld = [('largeoffice', 'pst80', 0.4),
       ('midriseapartment', 'new', 0.3),
       ('custombuilding', 'pre80', 0.3)]
property blddensity

Get or set building footprint density as fraction of urban area.

The sum of blddensity, grasscover and treecover must be less than or equal to 1.

property bldheight

Get or set average urban building height in meters.

property c_circ

Get or set wind scaling coefficient.

property c_exch

Get or set exchange velocity coefficient.

property charlength

Get or set the urban characteristic length in meters.

The characteristic length is the dimension of a square that encompasses the whole neighborhood.

property croad

Get or set road pavement volumetric heat capacity [J/m^3K].

property day

Get or set number (1-31) as simulation start day.

property droad

Get or set thickness of urban road pavement thickness in meters.

property dtsim

Get or set simulation timestep in seconds.

property dtweather

Get or set weather data timestep in seconds.

property epw_path

Get full path to rural .epw file to be morphed.

property flr_h

Get or set average building floor height in meters.

If value is None, a unique flr_h is set for each building from the refBEM. (Default: None).

property glzr

Get or set average building glazing ratio.

If value is None, a unique glzr is set for each building from the refBEM. (Default: None).

property grasscover

Get or set fraction of urban area covered exclusively in grass.

This value does not including grass under trees. The sum of blddensity, grasscover and treecover must be less than or equal to 1.

property h_mix

Get or set fraction of building HVAC waste heat released to street canyon.

It is assumed the rest of building HVAC waste heat is released from the roof.

property h_obs

Get or set rural average obstacle height in meters.

property h_ref

Get or set inversion height in meters.

property h_temp

Get or set temperature height in meters.

property h_ubl1

Get or set daytime urban boundary layer height in meters.

property h_ubl2

Get or set nighttime urban boundary layer height in meters.

property h_wind

Get or set wind height in meters.

property kroad

Get or set road pavement conductivity [W/mK].

property latfocc

Get or set latent heat fraction from occupant.

property latgrss

Get or set fraction of latent heat absorbed by urban grass.

property lattree

Get or set fraction of latent heat absorbed by urban trees.

property maxday

Get or set maximum heat flux threshold for daytime conditions [W/m].

property maxnight

Get or set maximum heat flux threshold for nighttime conditions [W/m2].

property month

Get or set number (1-12) as simulation start month.

property nday

Get or set number of days to simulate.

property new_epw_path

Get text string for new epw filepath.

property radfequip

Get or set radiant heat fraction from equipment.

property radflight

Get or set radiant heat fraction from electric light.

property radfocc

Get or set radiant heat fraction from occupant.

property refBEM

Get matrix of DOE reference BEMDefs defined by built type, era, and zone.

property refSchedule

Get matrix of DOE reference SchDefs defined by built type, era, and zone.

property ref_bem_vector

Get list of custom BEMDef objects to add to refBEM.

If value is None, all BEMDef objects are referenced from the DOE typologies defined by default in the refBEM matrix. (Default: None).

property ref_sch_vector

Get list of custom SchDef objects to add to refSchedule.

If value is None, all SchDef objects are referenced from the DOE typologies defined by default in the refSch matrix. (Default: None).

property rurvegcover

Get or set fraction of rural ground covered by vegetation.

property schtraffic

Get or set matrix for schedule of fractional anthropogenic heat load.

This property consists of a 3 x 24 matrix. Each row corresponding to a schedule for a weekday, Saturday, and Sunday, and each column corresponds to an hour in the day, for example:

# Weekday schedule
wkday = [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 schedule
satday = [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 schedule
sunday = [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]

schtraffic = [wkday, satday, sunday]
property sensanth

Get or set street level anthropogenic sensible heat [W/m2].

Street level anthropogenic heat is non-building heat like heat emitted from cars, pedestrians, and street cooking.

property sensocc

Get or set sensible heat from occupant [W].

property shgc

Get or set average building glazing Solar Heat Gain Coefficient.

If value is None, a unique shgc is set for each building from the refBEM. (Default: None).

property treecover

Get or set fraction of urban area covered in trees.

The sum of blddensity, grasscover and treecover must be less than or equal to 1.

property vegcover

Get fraction of urban ground covered by trees and grass.

property vegend

Get or set value from 1 to 12 for month at which vegetation stops evapotranspiration.

This month corresponds to when the leaves of vegetation are assumed to fall.

property vegroof

Get or set fraction of roofs covered in grass/shrubs.

If value is None, a unique vegroof is set for each building from the refBEM. (Default: None).

property vegstart

Get or set value from 1 to 12 for month at which vegetation starts to evapotranspire.

This month corresponds to when the leaves of vegetation are assumed to be out.

property vertohor

Get or set vertical-to-horizontal urban area ratio.

The vertical-to-horizontal urban area ratio is calculated by dividing the urban facade area by total urban area.

property windmin

Get or set minimum wind speed in m/s.

property zone

Get or set text representing an ASHRAE climate zone.

This value is used to specify climate zone-specific construction, and HVAC parameters for the DOE reference building types. This will not effect the simulation if only custom reference buildings are used.

Choose from the following:

  • ‘1A’ - (i.e Miami)

  • ‘1B’ - (i.e Kuwait)

  • ‘2A’ - (i.e Houston)

  • ‘2B’ - (i.e Phoenix)

  • ‘3A’ - (i.e Atlanta)

  • ‘3B-CA’ - (i.e Los Angeles)

  • ‘3B’ - (i.e Las Vegas)

  • ‘3C’ - (i.e San Francisco)

  • ‘4A’ - (i.e Baltimore)

  • ‘4B’ - (i.e Albuquerque)

  • ‘4C’ - (i.e Seattle)

  • ‘5A’ - (i.e Chicago)

  • ‘5B’ - (i.e Boulder)

  • ‘5C’ - (i.e Bremerton)

  • ‘6A’ - (i.e Minneapolis)

  • ‘6B’ - (i.e Helena)

  • ‘7’ - (i.e Duluth)

  • ‘8’ - (i.e Fairbanks)