py4design.py2radiance package

Module contents

class py4design.py2radiance.Rad(base_file_path, data_folder_path)

Bases: object

An object that contains all the neccessary information for running a Radiance/Daysim simulation.

Parameters:
base_file_path : str

The file path of the base.rad file. The base.rad file documents all the basic information of the simulation e.g. materials, constructions … It is distributed together with py2radiance.

data_folder_path : str

The directory to write all the results file to.

Examples

#initialise the rad class
>>> rad = Rad("C:\base.rad", "C:\rad_results")
#append surfaces for the simulation
>>> RadSurface("srfname1", [(0,0,0), (0,1,0), (1,1,0), (0,1,0)], "srfmat", rad)
#set sensor points
>>> rad.set_sensor_points([(0,0.2,0), (0,0.5,0)],[(0,0,1), (0,0,1)] )
#set the sky
>>> rad.set_sky( "!gensky 1 31 15 -c -a 1.3 -o -103.9 -m -120", (1,1,1), (0.2.0.2.0.2))
>>> rad.execute_oconv()
>>> dict_parm = {"ab": 2, "aa": 0.15, "ar": 128, "ad": 512, "as":256}
>>> rad.execute_rtrace(dict_parm)
#evaluate the result
>>> rad.eval_rad()
#for rpict rvu and falsecolor
>>> vp = (0,0,0)
>>> vd = (1,0,0)
>>> rad.execute_rvu(vp, vd, dict_parm)
>>> rad.execute_rpict("pict1", "640", "480", vp, vd, dict_parm)
>>> rad.execute_falsecolor("C:\i_pict.tif", "C:\l_pict.tif", "falsecolor_pict", "1000", "10", illuminance = True)
#FOR GENCUMULATIVE SKY MODULE
>>> rad = Rad("C:\base.rad", "C:\rad_results")
>>> RadSurface("srfname1", [(0,0,0), (0,1,0), (1,1,0), (0,1,0)], "srfmat", rad)
>>> rad.set_sensor_points([(0,0.2,0), (0,0.5,0)],[(0,0,1), (0,0,1)] )
#the gencumulative sky
>>> rad.execute_cumulative_oconv("7 19", "1 1 12 31", "c:\weatherfile.epw", output = "irradiance")
>>> rad.execute_cumulative_rtrace("2")
#FOR DAYSIM MODULE
>>> rad = Rad("C:\base.rad", "C:\rad_results")
>>> RadSurface("srfname1", [(0,0,0), (0,1,0), (1,1,0), (0,1,0)], "srfmat", rad)
#for daysim you need to create the sensor files
>>> rad.set_sensor_points([(0,0.2,0), (0,0.5,0)],[(0,0,1), (0,0,1)] )
>>> rad.create_sensor_input_file()
#initialise the daysim module
>>> rad.initialise_daysim("c:\daysim_dir")
#convert the epw to wea
>>> rad.execute_epw2wea(weatherfilepath)
#convert the rad files to daysim files
>>> rad.create_rad_input_file()
>>> rad.execute_radfiles2daysim()
#write the default radiance parameters
>>> rad.write_default_radiance_parameters()
#execute the gen_dc and ds_illum
>>> rad.execute_gen_dc("w/m2")
>>> rad.execute_ds_illum()
#evaluate the result
>>> res_dict = rad.eval_ill().
Attributes:
base_file_path : str

The file path of the base.rad file.

data_folder_path : str

The directory to write all the results file to.

command_file: str

The file path of the command.txt. The command file documents all the executed Radiance/Daysim commands.

surfaces: list of Surface class instances

The list of surfaces that will be analysed by Radiance/Daysim.

sensor_positions: 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_normals: 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_file_path : str

The file path of the sensor file.

rad_file_path : str

The file path of the rad file.

sky_file_path : str

The file path of the sky file.

oconv_file_path : str

The file path of the oconv file.

cumulative_sky_file_path : str

The file path of the cumulative sky file.

cumulative_oconv_file_path : str

The file path of the cumulative sky oconv file.

result_file : str

The file path of the result file.

cumulative_result_file_path : str

The file path of the cumulative result file.

daysimdir_ies : str

The daysim ies directory path.

daysimdir_pts : str

The daysim points directory path.

daysimdir_rad : str

The daysim rad directory path.

daysimdir_res : str

The daysim res directory path.

daysimdir_tmp : str

The daysim tmp directory path.

daysimdir_wea : str

The daysim wea directory path.

hea_file : str

The file path of the hea header daysim file.

hea_filename : str

The name of the hea header daysim file.

sunuphrs : int

The number of daylight hours in the weather file.
set_sensor_points(sensor_positions, sensor_normals)

This function sets the sensor points and their normals for the Radiance/Daysim simulation.

Parameters:
sensor_positions: 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_normals: 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), …]
create_sensor_input_file()

This function creates the sensor file. It requires the set_sensor_points() function to be executed prior to this function.

set_sky(gensky_command, sky_colour, ground_colour)

This function sets the gensky command and parameters.

Parameters:
gensky_command: str

The gensky command, e.g. “!gensky 1 31 15 -c -a 1.3 -o -103.9 -m -120”. The command is constructing a sky model for: Jan 31st at 15hr cloudy sky (-c) at latitude 1.3 and longitude -103.9 (to the east) and standard meridian -120 (to the east). The different sky models are -s sunny without sun, +s sunny with sun, -c cloudy sky, -i intermediate sky without sun, +i intermediate with sun, -u uniform cloudy sky. For more information visit: https://www.radiance-online.org/learning/documentation/manual-pages/pdfs/gensky.pdf/view

sky_colour: tuple of floats

A tuple of floats describing the sky colour. e.g. (1,1,1) for a white sky.

ground_colour: tuple of floats

A tuple of floats describing the ground colour. e.g. (0.2,0.2,0.2) for a grey ground.
create_sky_input_file()

This function creates the sky file. It requires the set_sky() function to be executed prior to this function.

create_rad_input_file()

This function creates the geometry rad file. It requires self.surfaces to be populated.

execute_oconv()

This function creates the geometry oconv file. It requires set_sky() to be executed prior and self.surfaces to be populated.

execute_rtrace(dict_parm)

This function executes the rtrace Radiance program and simulates the Irradiance. It requires the execute _oconv() to be executed prior.

Parameters:
dict_parm: dictionary

The dictionary needs to have the following keys and values: e.g. {“ab”: 2, “aa”: 0.15, “ar”: 128, “ad”: 512, “as”:256}. The parameters specify the parameters for the ray-tracing simulation. For more information visit: https://www.radiance-online.org/learning/documentation/manual-pages/pdfs/rtrace.pdf/view.
execute_rvu(vp, vd, dict_parm)

This function executes the rvu Radiance program and renders the scene. It requires the execute _oconv() to be executed prior.

Parameters:
vp: str

The focal point of a perspective view or the center of a parallel projection. e.g. “0 0 0”

vd: str

the view direction vector. The length of this vector indicates the focal distance. e.g. “1 0 0”

dict_parm: dictionary

The dictionary needs to have the following keys and values: e.g. {“ab”: 2, “aa”: 0.15, “ar”: 128, “ad”: 512, “as”:256}. The parameters specify the parameters for the ray-tracing simulation. For more information visit: https://www.radiance-online.org/learning/documentation/manual-pages/pdfs/rtrace.pdf/view.
execute_rpict(filename, x_resolution, y_resolution, vp, vd, dict_parm)

This function executes the rpict Radiance program and renders the scene. It requires the execute _oconv() to be executed prior.

Parameters:
filename: str

The name of generated tif picture. e.g. “pict1”. The picture will be saved to the data_folder_path. The tif file is a will have an angular fisheye distortion.

x_resolution: str

The x-resolution of the generated tif picture. e.g. “640”.

y_resolution: str

The y-resolution of the generated tif picture. e.g. “480”.

vp: str

The focal point of a perspective view or the center of a parallel projection. e.g. “0 0 0”.

vd: str

the view direction vector. The length of this vector indicates the focal distance. e.g. “1 0 0”.

dict_parm: dictionary

The dictionary needs to have the following keys and values: e.g. {“ab”: 2, “aa”: 0.15, “ar”: 128, “ad”: 512, “as”:256}. The parameters specify the parameters for the ray-tracing simulation. For more information visit: https://www.radiance-online.org/learning/documentation/manual-pages/pdfs/rtrace.pdf/view.
execute_falsecolour(i_basefile_path, l_basefile_path, filename, range_max, range_division, illuminance=True)

This function executes the rpict Radiance program and renders the scene. It requires the execute _oconv() to be executed prior.

Parameters:
i_basefile_path : str

The path of the illuminance tif picture. This tif picture can be generated using the execute_rpict)() function.

l_basefile_path : str

The path of the luminance tif picture. This tif picture can be generated using the execute_rpict)() function.

filename : str

The name of generated tif picture. e.g. “pict1”. The picture will be saved to the data_folder_path. The tif file is a will have an angular fisheye distortion.

range_max : str

The maximum value of the falsecolour. e.g. “1200”.

range_division : str

The division of the falsecolour. e.g. “10”.

illuminance : bool

True or False. If True will generate a falsecolour image of the illuminance value. If False will generate a falsecolour image of the luminance value.
render(filename, x_resolution, y_resolution, vp, vd, dict_parm)

This function executes the rpict Radiance program and renders the scene. It requires the execute _oconv() to be executed prior. The difference between render() and execute_rpict() is that this function do not produce illuminance and luminance tif.

Parameters:
filename: str

The name of generated tif picture. e.g. “pict1”. The picture will be saved to the data_folder_path. The tif file is a will have an angular fisheye distortion.

x_resolution: str

The x-resolution of the generated tif picture. e.g. “640”.

y_resolution: str

The y-resolution of the generated tif picture. e.g. “480”.

vp: str

The focal point of a perspective view or the center of a parallel projection. e.g. “0 0 0”.

vd: str

the view direction vector. The length of this vector indicates the focal distance. e.g. “1 0 0”.

dict_parm: dictionary

The dictionary needs to have the following keys and values: e.g. {“ab”: 2, “aa”: 0.15, “ar”: 128, “ad”: 512, “as”:256}. The parameters specify the parameters for the ray-tracing simulation. For more information visit: https://www.radiance-online.org/learning/documentation/manual-pages/pdfs/rtrace.pdf/view.
eval_rad()

This function reads the result file from the simulation and returns the results as a list.

Returns:
irradiance: list of floats

List of irradiance results (Wh/m2) that corresponds to the sensor points.

illuminance: list of floats

List of illuminance in (lux) results that corresponds to the sensor points.
create_cumulative_sky_input_file(time, date, weatherfile_path, output='irradiance')

This function sets the gencummulative sky command and parameters.

Parameters:
time: str

The time duration of the simulation e.g. “7 19”. This means the simulation will run from 7am to 7pm.

date: str

The dates of the simulation e.g. “1 1 12 31”. This means the simulation will run from Jan 1st to Dec 31st.

weatherfile_path: str

The file path of the weather file.

output: str, optional

The units of the results, “irradiance” (kWh/m2) or “illuminance” (lux), Default = “irradiance”.
execute_cumulative_oconv(time, date, weatherfile_path, output='irradiance')

This function executes the gencummulative oconv command and parameters.

Parameters:
time: str

The time duration of the simulation e.g. “7 19”. This means the simulation will run from 7am to 7pm.

date: str

The dates of the simulation e.g. “1 1 12 31”. This means the simulation will run from Jan 1st to Dec 31st.

weatherfile_path: str

The file path of the weather file.

output: str, optional

The units of the results, “irradiance” (kWh/m2) or “illuminance” (lux), Default = “irradiance”.
execute_cumulative_rtrace(ab)

This function executes the rtrace with the cummulative sky. This function requires the execution of execute_cumulative_oconv() prior.

Parameters:
ab: str

The number of ambient bounces for the ray-tracing. e.g. “2”.
eval_cumulative_rad(output='irradiance')

This function reads the cummulative result file from the simulation and returns the results as a list.

Parameters:
output: str, optional

The units of the results, “irradiance” (Wh/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 output parameter.
initialise_daysim(daysim_dir)

Run this method prior to running any Daysim simulation. This function creates the base .hea header file and all the neccessary folders for the Daysim simulation.

Parameters:
daysim_dir : str

The directory to write all the daysim results file to.
execute_epw2wea(epwweatherfile, ground_reflectance=0.2)

This function executes the epw2wea.exe and convert an epw weatherfile into a .wea weather file. Daysim uses .wea weatherfile.

Parameters:
epwweatherfile : str

The file path of the epw weather file.

ground_reflectance : float, optional

The ground reflectance, default = 0.2.
execute_radfiles2daysim()

This function executes the radfiles2daysim.exe and convert an all the rad geometry and material files to daysim files. The create_rad function needs to be executed prior to this function.

write_static_shading(hea_file)

This function writes the static shading into the hea file.

Parameters:
hea_file : open file mode “a”

The opened file of the header file.
write_radiance_parameters(rad_ab, rad_ad, rad_as, rad_ar, rad_aa, rad_lr, rad_st, rad_sj, rad_lw, rad_dj, rad_ds, rad_dr, rad_dp)

This function write the radiance parameters for the Daysim simulation.

Parameters:
rad_ab : int
rad_ad : int
rad_as : int
rad_ar : int
rad_aa : float
rad_lr : int
rad_st : float
rad_sj : float
rad_lw : float
rad_dj : float
rad_ds : float
rad_dr : int
rad_dp : int
write_default_radiance_parameters()

This function write the default radiance parameters for the Daysim simulation. The default settings are the complex scene 1 settings of daysimPS

execute_gen_dc(output_unit)

This function executes the gen_dc Daysim command.

Parameters:
output_unit : str, optional

The units of the results, “w/m2” or “lux”.
execute_ds_illum()

This function executes the ds_illum Daysim command.

eval_ill()

This function reads the daysim result file from the simulation and returns the results as a dictionaries.

Returns:
hourly results: list of dictionaries

List of Dictionaries of hourly irradiance results (Wh/m2) or illuminance in (lux) that corresponds to the sensor points depending on the output parameter. Each dictionary is an hour of results of all the sensor points. Each dictionary has key “date” and “result_list”. The “date” key points to a date string e.g. “12 31 23.500” which means Dec 31st 23hr indicating the date and hour of the result. The “result_list” key points to a list of results, which is the result of all the sensor points.
eval_ill_per_sensor()

This function reads the daysim result file from the simulation and returns a list of results.

Returns:
results per sensor : list of results

Each row is a sensor srf with 8760 colume of hourly result
class py4design.py2radiance.Surface(name, points, material)

Bases: object

An object that contains all the surface information running a Radiance/Daysim simulation.

Parameters:
name : str

The name of the surface.

points : pyptlist

List of points defining the surface. 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), …]

material : str

The name of the material of the surface. The material name must be in the base.rad file.
Attributes:
see Parameters.
class py4design.py2radiance.RadSurface(name, points, material, radgeom)

Bases: py4design.py2radiance.Surface

An object that contains all the surface information running a Radiance/Daysim simulation.

Parameters:
name : str

The name of the surface.

points : pyptlist

List of points defining the surface. 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), …]

material : str

The name of the material of the surface. The material name must be in the base.rad file.

radgeom : Rad class

The Rad class that contains all the information for running a Radiance/Daysim simulation.
Attributes:
see Parameters.
rad()

This function writes the surface information into Radiance readable string.

Returns:
rad surface : str

The surface writtenn into radiance readable string.
py4design.py2radiance.calculate_reflectance(r, g, b)

This function converts r g b into reflectance value based on the equation: reflectance = (0.2125 * r) + (0.7154 * g) + (0.0721 * b)

Parameters:
r : float

The r value.

g : float

The g value.

b : float

The b value.
Returns:
reflectance : float

The reflectance value.