py4design.urbanformeval module

py4design.urbanformeval.frontal_area_index(building_occsolids, boundary_occface, wind_dir, xdim=100, ydim=100)

This function calculates the frontal area index of an urban massing.

Parameters:

building_occsolids : a list of OCCsolids

The buildings to be analysed.

boundary_occface : OCCface

The boundary of the FAI analysis. This face will be gridded.

wind_dir : pyvec

Pyvec is a tuple of floats that documents the xyz vector of a dir e.g. (x,y,z)

xdim : float

X-dimension of the grid for the boundary occface, in metres (m)

ydim : float

Y-dimension of the grid for the boundary occface, in metres (m)
Returns:

result dictionary : dictionary

A dictionary with this keys : {“average”, “grids”, “fai_list”, “projected_surface_list” , “wind_plane_list”, “vertical_surface_list” }

average : float

Average frontal area index of the whole design.

grids : list of OCCfaces

The grid used for the frontal area index.

fai_list : list of floats

List of all the FAI of each grid.

projected_surface_list : list of OCCfaces

The projected surfaces merged together.

wind_plane_list : list of OCCfaces

The plane representing the direction of the wind

vertical_surface_list : list of OCCfaces

The facade surfaces that are projected.
py4design.urbanformeval.frontal_area_index_aplot(facade_occfaces, plane_occface, wind_dir)

This function calculates the frontal area index for a single grid.

Parameters:

facade_occfaces : list of OCCfaces

List of occfaces of vertical facades

plane_occface : OCCface

An occface that is the horizontal plane buildings are sitting on, the single grid.

wind_dir : pyvec

Pyvec is a tuple of floats that documents the xyz vector of a dir e.g. (x,y,z).
Returns:

fai : float

Frontal area index.

fuse_srfs : list of OCCfaces

The projected surfaces fused together

wind_plane : OCCface

The plane representing the direction of the wind

surfaces_projected : list of OCCfaces

the facade surfaces that are projected
py4design.urbanformeval.route_directness(network_occedgelist, plot_occfacelist, boundary_occface, obstruction_occfacelist=[], rdi_threshold=0.6)

This function measures the connectivity of street network in a neighbourhood by measuring route directness for each parcel to a series of points around the periphery of the study area. It identifies the percentage of good plots that exceed a rdi of 0.8 (urban area) and 0.6 (suburban). Algorithm for Route Directness Test, Stangl, P.. 2012 the pedestrian route directness test: A new level of service model. urban design international 17, 228-238.

Parameters:

network_occedgelist : list of OCCedges

The network to be analysed with nodes and edges.

plot_occfacelist : list of OCCfaces

The land use plots to be analysed.

boundary_occface : OCCface

The boundary of the analysed area.

obstruction_occface_list : list of OCCfaces, optional

The obstructions represented as OCCfaces for the analysis, default value = [].

rdi_threshold : float, optional

A threshold Route Directness Index, default value = 0.6.
Returns:

result dictionary : dictionary

A dictionary with this keys : {“average”, “percent”, “plots”, “pass_plots” , “fail_plots”, “rdi_list”, “network_edges”, “peripheral_points” }

average : float

Average rdi of the whole design.

percent : float

The percentage of the plots that has RDI higher than the threshold.

plots : list of OCCfaces

The plots that are analysed.

pass_plots : list of OCCfaces

The plots that has RDI higher than the threshold.

fail_plots : list of OCCfaces

The plots that has RDI lower than the threshold.

rdi_list : list of floats

The RDI of each plot, corresponds to the list of plots.

network_edges : list of OCCedges

The network that was analysed.

peripheral_points : list of OCCedges

The peripheral points visualised as OCCedges circles.
py4design.urbanformeval.calculate_route_directness(startpypt, peripheralpypt, obstruction_occfacelist, G, plot_area=None)

This function measures the route directness index of a plot.

Parameters:

startpypt : pypt

The mid point of the plot. Pypt is a tuple of floats. A pypt is a tuple that documents the xyz coordinates of a pt e.g. (x,y,z).

peripheralpypt : pypt

The end point. Pypt is a tuple of floats. A pypt is a tuple that documents the xyz coordinates of a pt e.g. (x,y,z).

obstruction_occface_list : list of OCCfaces

The obstructions represented as OCCfaces for the analysis.

G : Networkx Graph class instance

The networkx graph used for calculating the route distance of the shortest path between the mid point and ending point.

plot_area : float, optional

The area of the plot. If the area is less than 2023m2 (1/2 acre), the function will not consider the distane from the midpoint to the edge of the plot.
Returns:

rdi : float

The route directness index of the plot and this peripheral point. rdi = direct distance/ route distance.
py4design.urbanformeval.designate_peripheral_pts(boundary_occface, network_occedgelist, precision)

This function calculates the peripheral points around the boundary.

Parameters:

boundary_occface : OCCface

The boundary of the analysed area.

network_occedgelist : list of OCCedges

The network to be analysed with nodes and edges.

precision : float

The tolerance to be used for intersection calculations.
Returns:

peripheral_ptlist : pyptlist

The peripheral points. List of tuples of floats. A pypt is a tuple that documents the xyz coordinates of a pt e.g. (x,y,z), thus a pyptlist is a list of tuples e.g. [(x1,y1,z1), (x2,y2,z2), …].

pedgelist : list of OCCedges

The edges of the boundary.

interptlist : pyptlist

The intersections of the internal network and the boundary edges. List of tuples of floats. A pypt is a tuple that documents the xyz coordinates of a pt e.g. (x,y,z), thus a pyptlist is a list of tuples e.g. [(x1,y1,z1), (x2,y2,z2), …].
py4design.urbanformeval.connect_street_network2plot(network_occedgelist, plot_occfacelist, peripheral_n_inter_ptlist, precision)

This function connects the network edges to the mid point of each plot.

Parameters:

network_occedgelist : list of OCCedges

The network to be analysed with nodes and edges.

plot_occfacelist : list of OCCfaces

The land use plots to be analysed.

peripheral_n_inter_ptlist : pyptlist

The peripheral points and the intersections of the internal network and the boundary edges. List of tuples of floats. A pypt is a tuple that documents the xyz coordinates of a pt e.g. (x,y,z), thus a pyptlist is a list of tuples e.g. [(x1,y1,z1), (x2,y2,z2), …].

precision : float

The tolerance to be used for intersection calculations.
Returns:

new_network_occedgelist : list of OCCedges

The new network that has been connected to the plots.

midpt2_network_edgelist : list of OCCedges

The edges that connect the mid point of each plot to the new_network_occedgelist.

plot_midptlist : pyptlist

The mid points of all the plots. List of tuples of floats. A pypt is a tuple that documents the xyz coordinates of a pt e.g. (x,y,z), thus a pyptlist is a list of tuples e.g. [(x1,y1,z1), (x2,y2,z2), …].
py4design.urbanformeval.route_ard_obstruction(obstruction_face, crow_wire)

This function calculates the direct distance when met with an obstruction.

Parameters:

obstruction_face : OCCface

The obstructions represented as OCCface for the analysis.

crow_wire : OCCwire

The direct way from start to peripheral point not taking into account of the obstruction.
Returns:

new crow wire : OCCwire

The direct way from start to peripheral point taking into account of the obstruction. The wire will go around the obstruction OCCface.
py4design.urbanformeval.generate_directions(rot_degree)

This function generates a list of direction according to the interval of rotation degree.

Parameters:

rot_degree : float

The interval rotation degree.
Returns:

list of directions : pydirlist

The generated directions. List of tuples of floats. A pydir is a tuple that documents the xyz vector of a dir e.g. (x,y,z), thus a pydirlist is a list of tuples e.g. [(x1,y1,z1), (x2,y2,z2), …].
py4design.urbanformeval.construct_network_compound(network_occedgelist, extrusion_height)

This function extrudes the network edges and consolidate it into an OCCcompound.

Parameters:

network_occedgelist : list of OCCedges

The network to be analysed with nodes and edges.

extrusion_height : float

The extrusion height.
Returns:

extruded network compound : OCCcompound

The extruded network compound.
py4design.urbanformeval.draw_street_graph(networkx_graph, node_index)

This function draws the networkx graph and visualise it.

Parameters:

networkx_graph : networkx graph class instance

The networkx graph to be visualised.

node_index : list of floats

The index of the nodes in the networkx graph.
py4design.urbanformeval.nshffai(building_occsolids, irrad_threshold, epwweatherfile, xdim, ydim, rad_folderpath, nshffai_threshold=None, shading_occfaces=[])

This function calculates the Non-Solar Heated Facade to Floor Area Index (NSHFFAI) which is the ratio of the facade area that receives irradiation below a specified level over the net floor area. For more information refer to: Chen, Kian Wee, and Leslie Norford. 2017. Evaluating Urban Forms for Comparison Studies in the Massing Design Stage. Sustainability 9 (6). doi:10.3390/su9060987.

Parameters:

building_occsolids : list of OCCsolids

List of buildings occsolids to be analysed.

irrad_threshold : float

The solar irradiance threshold value (kwh/m2). For Singapore a tropical climate 364 kwh/m2 is used.

epwweatherfile : string

The file path of the epw weatherfile.

xdim : int

The x dimension grid size for the building facades.

ydim : int

The y dimension grid size

rad_folderpath : string

The file directory to store all the result files.

nshffai_threshold : float, optional

The nshffai threshold value for calculating the nshffai percent, default = None. If None, nshffai percent will return None.

shading_occfaces : list of OCCfaces, optional

The other surfaces to consider when running the Radiance simulation apart from the buildings of interest. e.g. surrounding terrain or buildings.
Returns:

result dictionary : dictionary

A dictionary with this keys : {“afi”, “ai”, “percent”, “sensor_surfaces” , “solar_results”, “building_solids”, “afi_list”}

afi : float

The nshffai of the urban design.

ai : float

The Non-Solar Heated Facade Area Index. The ratio of the facade area that receives irradiation below a specified level over the net facade area.

percent : float

The percentage of the buidings that has nshffai higher than the threshold.

sensor surfaces : list of OCCfaces

The gridded facade.

solar_results : list of floats

The the irradiance results in (kWh/m2), the list corresponds to the sensor surface list.

building_solids : list of OCCsolids

The OCCsolids of the buildings.

afi_list : list of floats

The nshffai of each building, the list corresponds to the building solids.
py4design.urbanformeval.usffai(building_occsolids, lower_irrad_threshold, upper_irrad_threshold, epwweatherfile, xdim, ydim, rad_folderpath, usffai_threshold=None, shading_occfaces=[])

This function calculates the Useful-Solar Facade to Floor Area Index (USFFAI) which is the ratio of the facade area that receives irradiation between the lower and upper solar threshold over the net floor area.

Parameters:

building_occsolids : list of OCCsolids

List of buildings occsolids to be analysed.

lower_irrad_threshold : float

The lower solar irradiance threshold value (kwh/m2). For Singapore a tropical climate 254 kwh/m2 is used.

upper_irrad_threshold : float

The upper solar irradiance threshold value (kwh/m2). For Singapore a tropical climate 364 kwh/m2 is used.

epwweatherfile : string

The file path of the epw weatherfile.

xdim : int

The x dimension grid size for the building facades.

ydim : int

The y dimension grid size

rad_folderpath : string

The file directory to store all the result files.

usffai_threshold : float, optional

The usffai threshold value for calculating the nshffai percent, default = None. If None, usffai percent will return None.

shading_occfaces : list of OCCfaces, optional

The other surfaces to consider when running the Radiance simulation apart from the buildings of interest. e.g. surrounding terrain or buildings.
Returns:

result dictionary : dictionary

A dictionary with this keys : {“afi”, “ai”, “percent”, “sensor_surfaces” , “solar_results”, “building_solids”, “afi_list”}

afi : float

The usffai of the urban design.

ai : float

The Useful-Solar Facade Area Index. The ratio of the facade area that receives irradiation between the thresholdsover the net facade area.

percent : float

The percentage of the buidings that has usffai higher than the threshold.

sensor surfaces : list of OCCfaces

The gridded facade.

solar_results : list of floats

The the irradiance results in (kWh/m2), the list corresponds to the sensor surface list.

building_solids : list of OCCsolids

The OCCsolids of the buildings.

afi_list : list of floats

The usffai of each building, the list corresponds to the building solids.
py4design.urbanformeval.calculate_epv(sensor_srflist, irrad_ress)

This function calculates the energy produced by PV (kwh/yr) (epv). epv = apv*fpv*gt*nmod*ninv apv is area of pv (m2) fpv is faction of surface with active solar cells (ratio) gt is total annual solar radiation energy incident on pv (kwh/m2/yr) nmod is the pv efficiency (12%) ninv is the avg inverter efficiency (90%)

Parameters:

sensor_srflist : list of OCCfaces

The gridded facade.

irrad_ress : list of floats

The the irradiance results in (kWh/m2), the list corresponds to the sensor surface list.
Returns:

epv : float

The energy produced by PV (kwh/yr).
py4design.urbanformeval.pvafai(building_occsolids, irrad_threshold, epwweatherfile, xdim, ydim, rad_folderpath, mode='roof', pvafai_threshold=None, shading_occfaces=[])

This function calculates the PhotoVoltaic Area to Floor Area Index (PVAFAI) which is the ratio of the PV area that receives irradiation above a specified level over the net floor area. For more information refer to: Chen, Kian Wee, and Leslie Norford. 2017. Evaluating Urban Forms for Comparison Studies in the Massing Design Stage. Sustainability 9 (6). doi:10.3390/su9060987.

Parameters:

building_occsolids : list of OCCsolids

List of buildings occsolids to be analysed.

irrad_threshold : float

The solar irradiance threshold value (kwh/m2). For Singapore a tropical climate 512 kwh/m2 is used for the facade and 1280 kWh/m2 is used for the roof.

epwweatherfile : string

The file path of the epw weatherfile.

xdim : int

The x dimension grid size for the building facades.

ydim : int

The y dimension grid size

rad_folderpath : string

The file directory to store all the result files.

mode : str, optional

The PV area of the building. Options are either “roof” or “facade”, default = “roof”.

pvafai_threshold : float, optional

The pvafai threshold value for calculating the pvafai percent, default = None. If None, nshffai percent will return None.

shading_occfaces : list of OCCfaces, optional

The other surfaces to consider when running the Radiance simulation apart from the buildings of interest. e.g. surrounding terrain or buildings.
Returns:

result dictionary : dictionary

A dictionary with this keys : {“afi”, “ai”, “percent”, “sensor_surfaces” , “solar_results”, “building_solids”, “afi_list”, “epv”}

afi : float

The pvafai of the urban design.

ai : float

The PV Area to Facade Area Index. The ratio of the facade area that receives irradiation below a specified level over the net facade area.

percent : float

The percentage of the buidings that has pvafai higher than the threshold.

sensor surfaces : list of OCCfaces

The gridded facade.

solar_results : list of floats

The the irradiance results in (kWh/m2), the list corresponds to the sensor surface list.

building_solids : list of OCCsolids

The OCCsolids of the buildings.

afi_list : list of floats

The pvafai of each building, the list corresponds to the building solids.

epv : float The energy produced by PV (kwh/yr).
py4design.urbanformeval.pvefai(building_occsolids, roof_irrad_threshold, facade_irrad_threshold, epwweatherfile, xdim, ydim, rad_folderpath, pvrfai_threshold=None, pvffai_threshold=None, pvefai_threshold=None, shading_occfaces=[])

This function calculates the PhotoVoltaic Envelope to Floor Area Index (PVEFAI) which is the ratio of the PV envelope area (both facade and roof) that receives irradiation above a specified level over the net floor area. For more information refer to: Chen, Kian Wee, and Leslie Norford. 2017. Evaluating Urban Forms for Comparison Studies in the Massing Design Stage. Sustainability 9 (6). doi:10.3390/su9060987.

Parameters:

building_occsolids : list of OCCsolids

List of buildings occsolids to be analysed.

roof_irrad_threshold : float

The solar irradiance threshold value (kwh/m2). For Singapore a tropical climate 1280 kWh/m2 is used for the roof.

facade_irrad_threshold : float

The solar irradiance threshold value (kwh/m2). For Singapore a tropical climate 512 kwh/m2 is used for the facade.

epwweatherfile : string

The file path of the epw weatherfile.

xdim : int

The x dimension grid size for the building facades.

ydim : int

The y dimension grid size

rad_folderpath : string

The file directory to store all the result files.

pvrfai_threshold : float, optional

The PV Roof to Floor Area Index (pvrfai) threshold value for calculating the pvrfai percent, default = None. If None, pvrfai percent will return None.

pvffai_threshold : float, optional

The PV Facade to Floor Area Index (pvffai) threshold value for calculating the pvffai percent, default = None. If None, pvffai percent will return None.

pvefai_threshold : float, optional

The PV Envelope to Floor Area Index (pvefai) threshold value for calculating the pvefai percent, default = None. If None, pvefai percent will return None.

shading_occfaces : list of OCCfaces, optional

The other surfaces to consider when running the Radiance simulation apart from the buildings of interest. e.g. surrounding terrain or buildings.
Returns:

result dictionary : dictionary

A dictionary with this keys : {“afi”, “ai”, “percent”, “sensor_surfaces” , “solar_results”, “building_solids”, “afi_list”, “epv”}

afi : list of floats

The pvefai, pvrfai and pvffai of the urban design.

ai : list of floats

The PV Envelope Area Index, PV Roof Area Index and PV Facade Area Index. The ratio of the envelope, roof or facade area that receives irradiation above a specified level over the net envelope, roof or facade area.

percent : list of floats

The percentage of the buidings that has pvefai, pvrfai and pvffai higher than the threshold.

sensor surfaces : list of OCCfaces

The gridded envelope surfaces.

solar_results : list of floats

The the irradiance results in (kWh/m2), the list corresponds to the sensor surface list.

building_solids : list of OCCsolids

The OCCsolids of the buildings.

afi_list : 2d list of floats

The pvefai, pvrfai and pvffai of each building, the list corresponds to the building solids. e.g. [[envelope_result_list],[roof_result_list], [facade_result_list]]

epv : float The energy produced by PV (kwh/yr) if the envelope is installed with PV.
py4design.urbanformeval.dffai(building_occsolids, illum_threshold, epwweatherfile, xdim, ydim, rad_folderpath, daysim_folderpath, dffai_threshold=None, shading_occfaces=[])

This function calculates the Daylight Facade to Floor Area Index (DFFAI) which is the ratio of the facade area that receives illuminance (lx) higher than a threshold over the net floor area.

Parameters:

building_occsolids : list of OCCsolids

List of buildings occsolids to be analysed.

illum_threshold : float

The illuminance threshold value (lx). For Singapore a tropical climate 10,000lx is used.

epwweatherfile : string

The file path of the epw weatherfile.

xdim : int

The x dimension grid size for the building facades.

ydim : int

The y dimension grid size

rad_folderpath : string

The file directory to store all the result files.

daysim_folderpath : string

The file directory to store all the daysim result files.

dffai_threshold : float, optional

The dffai threshold value for calculating the dffai percent, default = None. If None, dsffai percent will return None.

shading_occfaces : list of OCCfaces, optional

The other surfaces to consider when running the Radiance simulation apart from the buildings of interest. e.g. surrounding terrain or buildings.
Returns:

result dictionary : dictionary

A dictionary with this keys : {“afi”, “ai”, “percent”, “sensor_surfaces” , “solar_results”, “building_solids”, “afi_list”}

afi : float

The dffai of the urban design.

ai : float

The Daylight Facade Area Index. The ratio of the facade area that receives illuminance above the thresholds over the net facade area.

percent : float

The percentage of the buidings that has dffai higher than the threshold.

sensor surfaces : list of OCCfaces

The gridded facade.

solar_results : list of floats

The illuminance in (lx), the list corresponds to the sensor surface list.

building_solids : list of OCCsolids

The OCCsolids of the buildings.

afi_list : list of floats

The dffai of each building, the list corresponds to the building solids.
py4design.urbanformeval.initialise_srf_indexes(building_occsolids, xdim, ydim, rad_folderpath, surface='facade', shading_occfaces=[])

This function sorts all the building geometries and convert them into Radiance ready geometries.

Parameters:

building_occsolids : list of OCCsolids

List of buildings occsolids to be analysed.

xdim : int

The x dimension grid size for the building facades.

ydim : int

The y dimension grid size

rad_folderpath : string

The file directory to store all the result files.

surface : string, optional

The string specifying what are the surface types to extract from the OCCsolid for the analysis. Options are: “facade”, “roof” and “envelope”, default = “facade”.

shading_occfaces : list of OCCfaces, optional

The other surfaces to consider when running the Radiance simulation apart from the buildings of interest. e.g. surrounding terrain or buildings.
Returns:

rad : py2radiance Rad class instance

The class stores all the Radiance ready geometries.

sensor_ptlist : pyptlist

List of positions for sensing. Pyptlist is a list of tuples of floats. A pypt is a tuple that documents the xyz coordinates of a pt e.g. (x,y,z), thus a pyptlist is a list of tuples e.g. [(x1,y1,z1), (x2,y2,z2), …]

sensor_dirlist : pyveclist

List of normals of the points sensing. Pyveclist is a list of tuples of floats. A pyvec is a tuple that documents the xyz coordinates of a direction e.g. (x,y,z), thus a pyveclist is a list of tuples e.g. [(x1,y1,z1), (x2,y2,z2), …]

sensor_surfacelist : list of OCCfaces

The gridded facade.

bldg_dictlist : list of dictionaries

List of dictionaries. Each dictionary documents information on a building. Each dictionary has these keys : {“solid”, “surface_index”}

solid : OCCsolid

The building OCCsolid.

surface_index : list of int

The integers are index to the sensor_surfacelist. It specifies which surfaces in the sensor_surfacelist belongs to this building. if the parameter surface == “envelope”, the bldg_dict[“surface_index”] = [envelope_index1, envelope_index2,roof_index1,roof_index2,facade_index1,facade_index2]. if the parameter surface == “facade” or “roof”, bldg_dict[“surface_index”] = [surface_index1,surface_index2].
py4design.urbanformeval.execute_cummulative_radiance(rad, start_mth, end_mth, start_date, end_date, start_hr, end_hr, epwweatherfile, mode='irradiance')

This function executes Radiance on the buildings.

Parameters:

rad : py2radiance Rad class instance

The class stores all the Radiance ready geometries.

start_mth : int

The start month of the simulation e.g. 1. This means the simulation will run from Jan.

end_mth : int

The end month of the simulation e.g. 12. This means the simulation will end on Dec.

start_date : int

The start date of the simulation e.g. 1. This means the simulation will start on the 1st of the start mth.

end_date : int

The start date of the simulation e.g. 31. This means the simulation will end on the 31st of the end mth.

start_hr : int

The start hour of the simulation e.g. 7. This means the simulation will start on 7 am everyday.

end_hr : int

The end hour of the simulation e.g. 19. This means the simulation will end on 7 pm everyday.

epwweatherfile : string

The file path of the epw weatherfile.

mode : string

The units of the results, “irradiance” (kWh/m2) or “illuminance” (lux), default = “irradiance”.
Returns:

results : list of floats

List of irradiance results (kWh/m2) or illuminance in (lux) that corresponds to the sensor points depending on the mode parameter.
py4design.urbanformeval.get_afi_dict(result_list, sensor_srflist, bldgdict_list, surface='all_surfaces')

This function rearrange the surfaces of a building accordingly for calculate_afi function after the execution of Radiance.

Parameters:

result_list : list of floats

List of irradiance results (kWh/m2) or illuminance in (lux) depending on the intention to cacluate either nshffai, usffai or dffai. The list corresponds to the sensor_surfacelist.

sensor_surfacelist : list of OCCfaces

The gridded facade.

bldg_dictlist : list of dictionaries

List of dictionaries generated from the function initialise_srf_indexes(). Each dictionary documents information on a building. Each dictionary has these keys : {“solid”, “surface_index”}

surface : string, optional

The string specifying what are the surface types to extract from the OCCsolid for the analysis. Options are: “all_surfaces”, “facade” and “roof”, default = “all_surfaces”.
Returns:

sorted_bldg_dictlist : list of dictionaries

List of dictionaries. Each dictionary documents information on a building. Each dictionary has these keys : {“solid”, “surface”, “result”}

solid : OCCsolid

The building OCCsolid.

surface : list of OCCfaces

The surfaces that belongs to this building.

result : list of floats

List of irradiance results (kWh/m2) or illuminance in (lux) depending on the intention to cacluate either nshaffai, usffai, pvefai, pvafai or dffai. The list corresponds to the surface.
py4design.urbanformeval.calculate_shape_factor(bldg_occsolid_list, flr2flr_height)

This function calculates the shape factor of all the buildings. The shape factor is the ratio of building envelope surface area over the building floor area.

Parameters:

bldg_occsolid_list : list of OCCsolids

The list of OCCsolids that are buildings to be calculated.

flr2flr_height : float

The floor to floor height the building.
Returns:

total_bldg_shape_factor_list : list of floats

The list of shape factor of all the buildings.
py4design.urbanformeval.calculate_afi(bldgdict_list, result_threshold, mode, flr2flr_height=3.0, afi_threshold=None)

This function calculates the x (either envelope, roof or facade) area to floor area index.

Parameters:

bldgdict_list : list of dictionaries

List of dictionaries generated from the function get_afi_dict(). Each dictionary documents information on a building. Each dictionary has these keys : {“solid”, “surface”, “result”}

result_threshold : float

The threshold value either irradiance (kWh/m2) or illuminance (lx) depending on the intention to calculate nshaffai, pvefai, pvafai or dffai.

mode : str

The options are “nshffai”, “pvefai” or “dffai”. Mode “pvefai” is used form both function pvafai() and pvefai().

flr2flr_height : float, optional

The floor to floor height the building, default = 3.0.

afi_threshold : float, optional

The afi threshold value for calculating the afi percent, default = None. If None, afi percent will return None.
Returns:

afi : float

The afi of the urban design.

ai : float

The Facade Area Index. The ratio of the facade area that receives x (illuminance or irradiance) above/below the thresholds over the net facade area.

percent : float

The percentage of the buidings that has afi higher/lower than the threshold.

high_perf_area_list : list of floats

The list of the area of the facade/roof/envelope area performing above/below the threshold.

sa_list : list of floats

The list of the area of the facade/roof/envelope of the building.

shape_factor_list : list of floats

The list of the shape factor of the buildings.

bsolid_list : list of OCCsolids

The OCCsolids of the buildings.

afi_list : list of floats

The afi of each building, the list corresponds to the building solids.
py4design.urbanformeval.calculate_afi2(bldgdict_list, lower_result_threshold, upper_result_threshold, mode, flr2flr_height=3.0, afi_threshold=None)

This function calculates the x (either envelope, roof or facade) area to floor area index.

Parameters:

bldgdict_list : list of dictionaries

List of dictionaries generated from the function get_afi_dict(). Each dictionary documents information on a building. Each dictionary has these keys : {“solid”, “surface”, “result”}

lower_result_threshold : float

The lower threshold value irradiance (kWh/m2).

upper_result_threshold : float

The upper threshold value irradiance (kWh/m2).

mode : str

The options are “usffai”.

flr2flr_height : float, optional

The floor to floor height the building, default = 3.0.

afi_threshold : float, optional

The afi threshold value for calculating the afi percent, default = None. If None, afi percent will return None.
Returns:

afi : float

The afi of the urban design.

ai : float

The Facade Area Index. The ratio of the facade area that receives x (illuminance or irradiance) above/below the thresholds over the net facade area.

percent : float

The percentage of the buidings that has afi higher/lower than the threshold.

high_perf_area_list : list of floats

The list of the area of the facade/roof/envelope area performing above/below the threshold.

sa_list : list of floats

The list of the area of the facade/roof/envelope of the building.

shape_factor_list : list of floats

The list of the shape factor of the buildings.

bsolid_list : list of OCCsolids

The OCCsolids of the buildings.

afi_list : list of floats

The afi of each building, the list corresponds to the building solids.