ladybug_radiance.skymatrix module

Get a matrix containing radiation values from each patch of a sky dome.

Creating this matrix is a necessary pre-step before doing incident radiation analysis or generating a visualizations like a radiation rose.

This class uses Radiance’s gendaymtx function to calculate the radiation for each patch of the sky. Gendaymtx is written by Ian Ashdown and Greg Ward. More information can be found in Radiance manual at: http://www.radiance-online.org/learning/documentation/manual-pages/pdfs/gendaymtx.pdf

class ladybug_radiance.skymatrix.SkyMatrix(wea, north=0, high_density=False, ground_reflectance=0.2)[source]

Bases: object

A matrix containing radiation values from each patch of a sky dome.

Parameters:

  • wea – A Ladybug Wea object.

  • north – A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).

  • high_density – A Boolean to indicate whether the higher-density Reinhart sky matrix should be generated (True), which has roughly 4 times the sky patches as the (default) original Tregenza sky (False). Note that, while the Reinhart sky has a higher resolution and is more accurate, it will result in considerably longer calculation time for incident radiation studies. (Default: False).

  • ground_reflectance – A number between 0 and 1 to note the average ground reflectance that is associated with the sky matrix. (Default: 0.2).

Properties:

  • wea

  • north

  • high_density

  • ground_reflectance

  • benefit_matrix

  • folder

  • wea_duration

  • direct_values

  • diffuse_values

  • metadata

  • data

ToString()[source]

Overwrite .NET ToString.

compute_sky()[source]

Compute the values of the sky matrix.

classmethod from_ashrae_clear_sky(location, sky_clearness=1, hoys=None, north=0, high_density=False, ground_reflectance=0.2)[source]

Create an original ASHRAE Clear SkyMatrix using a location and sky clearness.

The original ASHRAE Clear Sky is intended to determine peak solar load and sizing parameters for HVAC systems. It is not the sky model currently recommended by ASHRAE since it usually overestimates the amount of solar irradiance in comparison to the newer ASHRAE Revised Clear Sky (“Tau Model”). However, the original model here is still useful for cases where monthly optical depth values are not known. For more information on the ASHRAE Clear Sky model, see the EnergyPlus Engineering Reference: https://bigladdersoftware.com/epx/docs/8-9/engineering-reference/climate-calculations.html

Parameters:

  • location – Ladybug location object.

  • sky_clearness – A factor that will be multiplied by the output of the model. This is to help account for locations where clear, dry skies predominate (e.g., at high elevations) or, conversely, where hazy and humid conditions are frequent. See Threlkeld and Jordan (1958) for recommended values. Typical values range from 0.95 to 1.05 and are usually never more than 1.2. Default is set to 1.0.

  • hoys – A list of numbers between 0 and 8760 that represent the hours of the year for which to generate the sky matrix. If None, the matrix will be for the entire year. (Default: None).

  • north – A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).

  • high_density – A Boolean to indicate whether the higher-density Reinhart sky matrix should be generated (True), which has roughly 4 times the sky patches as the (default) original Tregenza sky (False). Note that, while the Reinhart sky has a higher resolution and is more accurate, it will result in considerably longer calculation time for incident radiation studies. (Default: False).

  • ground_reflectance – A number between 0 and 1 to note the average ground reflectance that is associated with the sky matrix. (Default: 0.2).

classmethod from_components(location, direct_normal_irradiance, diffuse_horizontal_irradiance, hoys=None, north=0, high_density=False, ground_reflectance=0.2)[source]

Create a SkyMatrix from individual solar irradiance components.

Parameters:

  • location – Ladybug location object.

  • direct_normal_irradiance – A HourlyContinuousCollection or a HourlyDiscontinuousCollection for direct normal irradiance. The collection must be aligned with the diffuse_horizontal_irradiance.

  • diffuse_horizontal_irradiance – A HourlyContinuousCollection or a HourlyDiscontinuousCollection for diffuse horizontal irradiance, The collection must be aligned with the direct_normal_irradiance.

  • hoys – A list of numbers between 0 and 8760 that represent the hours of the year for which to generate the sky matrix. If None, the matrix will be for the entire year. (Default: None).

  • north – A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).

  • high_density – A Boolean to indicate whether the higher-density Reinhart sky matrix should be generated (True), which has roughly 4 times the sky patches as the (default) original Tregenza sky (False). Note that, while the Reinhart sky has a higher resolution and is more accurate, it will result in considerably longer calculation time for incident radiation studies. (Default: False).

  • ground_reflectance – A number between 0 and 1 to note the average ground reflectance that is associated with the sky matrix. (Default: 0.2).

classmethod from_components_benefit(location, direct_normal_irradiance, diffuse_horizontal_irradiance, temperature, balance_temperature=15, balance_offset=2, hoys=None, north=0, high_density=False, ground_reflectance=0.2)[source]

Create a SkyMatrix representing benefit/harm based on temperature data.

Parameters:

  • location – Ladybug location object.

  • direct_normal_irradiance – A HourlyContinuousCollection or a HourlyDiscontinuousCollection for direct normal irradiance. The collection must be aligned with the diffuse_horizontal_irradiance.

  • diffuse_horizontal_irradiance – A HourlyContinuousCollection or a HourlyDiscontinuousCollection for diffuse horizontal irradiance. The collection must be aligned with the direct_normal_irradiance.

  • temperature – A HourlyContinuousCollection or a HourlyDiscontinuousCollection for temperature, which will be used to establish whether radiation is desired or not for each time step. The collection must be aligned with the irradiance inputs.

  • balance_temperature – The temperature in Celsius between which radiation switches from being a benefit to a harm. Typical residential buildings have balance temperatures as high as 18C and commercial buildings tend to have lower values around 12C. (Default 15C).

  • balance_offset – The temperature offset from the balance temperature in Celsius where radiation is neither harmful nor helpful. (Default: 2).

  • hoys – A list of numbers between 0 and 8760 that represent the hours of the year for which to generate the sky matrix. If None, the matrix will be for the entire year. (Default: None).

  • north – A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).

  • high_density – A Boolean to indicate whether the higher-density Reinhart sky matrix should be generated (True), which has roughly 4 times the sky patches as the (default) original Tregenza sky (False). Note that, while the Reinhart sky has a higher resolution and is more accurate, it will result in considerably longer calculation time for incident radiation studies. (Default: False).

  • ground_reflectance – A number between 0 and 1 to note the average ground reflectance that is associated with the sky matrix. (Default: 0.2).

classmethod from_epw(epw_file, hoys=None, north=0, high_density=False, ground_reflectance=0.2)[source]

Create a SkyMatrix using the solar irradiance values in an epw file.

Parameters:

  • epw_file – Full path to epw weather file.

  • hoys – A list of numbers between 0 and 8760 that represent the hours of the year for which to generate the sky matrix. If None, the matrix will be for the entire year. (Default: None).

  • north – A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).

  • high_density – A Boolean to indicate whether the higher-density Reinhart sky matrix should be generated (True), which has roughly 4 times the sky patches as the (default) original Tregenza sky (False). Note that, while the Reinhart sky has a higher resolution and is more accurate, it will result in considerably longer calculation time for incident radiation studies. (Default: False).

  • ground_reflectance – A number between 0 and 1 to note the average ground reflectance that is associated with the sky matrix. (Default: 0.2).

classmethod from_epw_benefit(epw_file, balance_temperature=15, balance_offset=2, hoys=None, north=0, high_density=False, ground_reflectance=0.2)[source]

Create a SkyMatrix using the solar irradiance values in an epw file.

Parameters:

  • epw_file – Full path to epw weather file.

  • balance_temperature – The temperature in Celsius between which radiation switches from being a benefit to a harm. Typical residential buildings have balance temperatures as high as 18C and commercial buildings tend to have lower values around 12C. (Default 15C).

  • balance_offset – The temperature offset from the balance temperature in Celsius where radiation is neither harmful nor helpful. (Default: 2).

  • hoys – A list of numbers between 0 and 8760 that represent the hours of the year for which to generate the sky matrix. If None, the matrix will be for the entire year. (Default: None).

  • north – A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).

  • high_density – A Boolean to indicate whether the higher-density Reinhart sky matrix should be generated (True), which has roughly 4 times the sky patches as the (default) original Tregenza sky (False). Note that, while the Reinhart sky has a higher resolution and is more accurate, it will result in considerably longer calculation time for incident radiation studies. (Default: False).

  • ground_reflectance – A number between 0 and 1 to note the average ground reflectance that is associated with the sky matrix. (Default: 0.2).

classmethod from_stat(stat_file, hoys=None, north=0, high_density=False, ground_reflectance=0.2)[source]

Create a ASHRAE Revised Clear SkyMatrix using the data in .stat file.

The .stat file must have monthly sky optical depths within it in order to create a Wea this way.

Parameters:

  • stat_file – Full path to a .stat file.

  • hoys – A list of numbers between 0 and 8760 that represent the hours of the year for which to generate the sky matrix. If None, the matrix will be for the entire year. (Default: None).

  • north – A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).

  • high_density – A Boolean to indicate whether the higher-density Reinhart sky matrix should be generated (True), which has roughly 4 times the sky patches as the (default) original Tregenza sky (False). Note that, while the Reinhart sky has a higher resolution and is more accurate, it will result in considerably longer calculation time for incident radiation studies. (Default: False).

  • ground_reflectance – A number between 0 and 1 to note the average ground reflectance that is associated with the sky matrix. (Default: 0.2).

LINE_BREAK = b'\n'
PATCHES_PER_ROW = {1: (30, 30, 24, 24, 18, 12, 6, 1), 2: (60, 60, 60, 60, 48, 48, 48, 48, 36, 36, 24, 24, 12, 12, 1)}
PATCH_ROW_COEFF = {1: (0.0435449227, 0.0416418006, 0.0473984151, 0.0406730411, 0.0428934136, 0.0445221864, 0.0455168385, 0.0344199465), 2: (0.0113221971, 0.0111894547, 0.0109255262, 0.0105335058, 0.0125224872, 0.0117312774, 0.0108025291, 0.00974713106, 0.011436609, 0.00974295956, 0.0119026242, 0.00905126163, 0.0121875626, 0.00612971396, 0.00921483254)}
SEPARATOR = b' '
property benefit_matrix

Get or set list of True/False values for whether Wea datetimes are beneficial.

This list must have a length that matches the Wea so that each datetime can be matched with a benefit/harm value. True (beneficial) values will contribute positively to the value of each sky patch while False (harmful) values will contribute negatively. A value of None in the list indicates that the hour has neither a benefit or a harmful effect.

This is None by default, indicating that all radiation values contribute positively to each sky patch.

property data

Get a matrix of all data associated with the sky matrix.

The first list contains metadata, followed by direct values and then diffuse values.

property diffuse_values

Get the diffuse radiation values for each of the sky patches.

property direct_values

Get the direct radiation values for each of the sky patches.

property folder

Get or set the folder in which the Radiance commands are executed.

If None, it will be written to Ladybug’s default EPW folder.

property ground_reflectance

Get or set a number between 0 and 1 to note the average ground reflectance.

property high_density

Get or set a boolean for whether the sky is a higher-density Reinhart matrix.

property metadata

Get a list of metadata associated with the sky matrix.

property north

Get or set a number north direction.

A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East.

property wea

Get or set a Wea object for the sky matrix.

property wea_duration

Get the duration of the Wea in hours.

This is useful for converting the radiation values of the sky patches (kWh/m2) into irradiance (W/m2).