ladybug_radiance.study.radiation module

Class for visualizing incident radiation (or irradiance) falling onto a mesh.

class ladybug_radiance.study.radiation.RadiationStudy(sky_matrix, study_mesh, context_geometry, offset_distance=0, by_vertex=False, sim_folder=None, use_radiance_mesh=False)[source]

Bases: object

Visualize the incident radiation (or irradiance) falling onto a study_mesh.

Such studies of incident radiation can be used to approximate the energy that can be collected from photovoltaic or solar thermal systems. They are also useful for evaluating the impact of a building’s orientation on both energy use and the size/cost of cooling systems. For studies of photovoltaic potential or building energy use impact, a sky matrix from EPW radiation should be used. For studies of cooling system size/cost, a sky matrix derived from the STAT file’s clear sky radiation should be used.

Not that no reflections of solar energy are included in the analysis performed by this class. Ground reflected irradiance is crudely accounted for by means of an emissive “ground hemisphere,” which is like the sky dome hemisphere and is derived from the ground reflectance that is associated with the connected sky_matrix. This means that including geometry that represents the ground surface will effectively block such crude ground reflection.

Parameters:

  • sky_matrix – A SkyMatrix object, which describes the radiation coming from the various patches of the sky.

  • study_mesh – A ladybug geometry Mesh3D, which represents the geometry on which the incident radiation is being studied.

  • context_geometry – A list of ladybug geometry Face3D and/or Mesh3D that can block the view to the sky and ground.

  • offset_distance – An optional number to offset the sensor points before the vectors are cast through the context_geometry. (Default: 0).

  • by_vertex – A boolean to indicate whether the study should be run for each vertex of the study_mesh (True) or each face of the study mesh (False). (Default: False).

  • sim_folder – An optional path to a folder where the simulation files will be written. If None, a temporary directory will be used. (Default: None).

  • use_radiance_mesh – A boolean to note whether input Mesh3D should be translated to Radiance Meshes for simulation or whether they should simply have their faces translated to Radiance polygons. For complex context geometry, Radiance meshes will use less memory but they take a longer time to prepare compared to polygons. (Default: False).

Properties:

  • sky_matrix

  • study_mesh

  • context_geometry

  • offset_distance

  • by_vertex

  • sim_folder

  • use_radiance_mesh

  • study_points

  • study_normals

  • intersection_matrix

  • radiation_values

  • irradiance_values

  • metadata

  • is_benefit

ToString()[source]

Overwrite .NET ToString.

compute()[source]

Compute the radiation values of the study.

Note that this method is automatically called under the hood when accessing any results of the study and these results have not already been computed. So using this method is not necessary to correctly use this class. However, explicitly calling this method can help control when the time consuming part of the study runs, which is particularly helpful for larger studies.

draw(legend_parameters=None, plot_irradiance=False)[source]

Draw a colored study_mesh, compass, graphic/legend, and title.

Parameters:

  • legend_parameters – An optional LegendParameter object to change the display of the radiation study. If None, default legend parameters will be used. (Default: None).

  • plot_irradiance – Boolean to note whether the results should be plotted with units of total Radiation (kWh/m2) [False] or with units of average Irradiance (W/m2) [True]. (Default: False).

Returns:

A tuple with three values.

  • colored_mesh – A colored Mesh3D for the study results.

  • graphic – A GraphicContainer for the colored mesh, indicating the

    legend and title location for the study.

  • title – Text for the title of the study.

total_radiation(conversion_to_meters=1)[source]

Get a number for the total radiation of the study in kWh.

Note that, when the study is run by_vertex, it is assumed that all vertices represent the same area.

Parameters:

conversion_to_meters – A number (typically less than 1) to note the conversion factor from the mesh area to square meters. This should be a conversion in square units and not just linear units. (Default: 1).

property by_vertex

Get or set a boolean for whether the study should be run for each vertex.

property context_geometry

Get or set a tuple of Face3D and Mesh3D for the geometry that can block sun.

property intersection_matrix

Get a list of lists for the intersection matrix computed by the study.

property irradiance_values

Get a list of values for the irradiance results of the study in W/m2.

property is_benefit

Get a boolean to note whether the sky matrix includes benefit information.

property metadata

Get a tuple of information about the metadata assigned to the study.

property offset_distance

Get or set a number for the offset distance used in the study.

property radiation_values

Get a list of values for the radiation results of the study in kWh/m2.

property sim_folder

Get or set text for the path where the simulation files are written.

property sky_matrix

Get or set a SkyMatrix object for the sky used in the study.

property study_mesh

Get or set a SkyMatrix object for the sky used in the study.

property study_normals

Get a tuple of Vector3Ds for the normals of the study.

property study_points

Get a tuple of Point3Ds for the points of the study.

property use_radiance_mesh

Get or set a boolean for whether Radiance Meshes are used in the simulation.