ladybug_comfort.solarcal module¶
Functions for adjusting MRT for radiative sky exchange (including shortwave solar).
The solarcal formulas of this module are taken from the following publications:
[1] Arens, E., T. Hoyt, X. Zhou, L. Huang, H. Zhang and S. Schiavon. 2015. Modeling the comfort effects of short-wave solar radiation indoors. Building and Environment, 88, 3-9. http://dx.doi.org/10.1016/j.buildenv.2014.09.004 https://escholarship.org/uc/item/89m1h2dg
[2] ASHRAE Standard 55 (2017). “Thermal Environmental Conditions for Human Occupancy”.
- Properties:
- SOLARCAL_SPLINES:
A dictionary with two keys: ‘standing’ and ‘seated’. Each value for these keys is a 2D matrix of projection factors for human geometry. Each row refers to an degree of azimuth and each colum refers to a degree of altitude.
- ladybug_comfort.solarcal.body_diff_from_diff_horiz(diff_horiz_solar, sky_exposure=1, fract_efficiency=0.725)[source]¶
Estimate the diffuse solar flux on human geometry from diffuse horizontal solar.
- Parameters:
diff_horiz_solar – Diffuse horizontal solar irradiance in W/m2.
sky_exposure – A number between 0 and 1 representing the fraction of the sky vault in occupant’s view. Default is 1 for outdoors in an open field.
fract_efficiency – A number representing the fraction of the body surface exposed to radiation from the environment. This is typically either 0.725 for a standing or supine person or 0.696 for a seated person. Default is 0.725 for a standing person.
- ladybug_comfort.solarcal.body_dir_from_dir_horiz(dir_horiz_solar, altitude, sharp=135, posture='standing', fract_exposed=1)[source]¶
Estimate the direct solar flux on human geometry from direct horizontal solar.
- Parameters:
dir_horiz_solar – Direct horizontal solar irradiance in W/m2.
altitude – A number between 0 and 90 representing the altitude of the sun in degrees.
sharp – A number between 0 and 180 representing the solar horizontal angle relative to front of person (SHARP). 0 signifies sun that is shining directly into the person’s face and 180 signifies sun that is shining at the person’s back. Default is 135, assuming that a person typically faces their side or back to the sun to avoid glare.
posture – A text string indicating the posture of the body. Letters must be lowercase. Choose from the following: “standing”, “seated”, “supine”. Default is “standing”.
fract_exposed – A number between 0 and 1 representing the fraction of the body exposed to direct sunlight. Note that this does not include the body’s self-shading; only the shading from surroundings. Default is 1 for a person in an open area.
- ladybug_comfort.solarcal.body_dir_from_dir_normal(dir_normal_solar, altitude, sharp=135, posture='standing', fract_exposed=1)[source]¶
Estimate the direct solar flux on human geometry from direct horizontal solar.
- Parameters:
dir_normal_solar – Direct normal solar irradiance in W/m2.
altitude – A number between 0 and 90 representing the altitude of the sun in degrees.
sharp – A number between 0 and 180 representing the solar horizontal angle relative to front of person (SHARP). 0 signifies sun that is shining directly into the person’s face and 180 signifies sun that is shining at the person’s back. Default is 135, assuming that a person typically faces their side or back to the sun to avoid glare.
posture – A text string indicating the posture of the body. Letters must be lowercase. Choose from the following: “standing”, “seated”, “supine”. Default is “standing”.
fract_exposed – A number between 0 and 1 representing the fraction of the body exposed to direct sunlight. Note that this does not include the body’s self-shading; only the shading from surroundings. Default is 1 for a person in an open area.
- ladybug_comfort.solarcal.body_ref_from_glob_horiz(glob_horiz_solar, floor_reflectance=0.25, sky_exposure=1, fract_efficiency=0.725)[source]¶
Estimate floor-reflected solar flux on human geometry from global horizontal solar.
- Parameters:
glob_horiz_solar – Global horizontal solar irradiance in W/m2.
floor_reflectance – A number between 0 and 1 the represents the reflectance of the floor. Default is for 0.25 which is characteristic of outdoor grass or dry bare soil.
sky_exposure – A number between 0 and 1 representing the fraction of the sky vault in occupant’s view. Default is 1 for outdoors in an open field.
fract_efficiency – A number representing the fraction of the body surface exposed to radiation from the environment. This is typically either 0.725 for a standing or supine person or 0.696 for a seated person. Default is 0.725 for a standing person.
- ladybug_comfort.solarcal.body_ref_from_ref_horiz(ref_horiz_solar, sky_exposure=1, fract_efficiency=0.725)[source]¶
Estimate floor-reflected flux on human geometry from reflected horizontal solar.
- Parameters:
ref_horiz_solar – Ground-reflected horizontal solar irradiance in W/m2.
sky_exposure – A number between 0 and 1 representing the fraction of the sky vault in occupant’s view. Default is 1 for outdoors in an open field.
fract_efficiency – A number representing the fraction of the body surface exposed to radiation from the environment. This is typically either 0.725 for a standing or supine person or 0.696 for a seated person. Default is 0.725 for a standing person.
- ladybug_comfort.solarcal.body_solar_flux_from_horiz_components(diff_horiz_solar, dir_horiz_solar, ref_horiz_solar, altitude, sharp=135, fract_exposed=1, posture='standing')[source]¶
Estimate total solar flux on human geometry from horizontal components.
This method is useful for cases when one wants to take the hourly results of a spatial radiation study with Radiance and use them to build a map of ERF or MRT delta on a person.
- Parameters:
diff_horiz_solar – Diffuse horizontal solar irradiance in W/m2.
dir_horiz_solar – Direct horizontal solar irradiance in W/m2.
ref_horiz_solar – Ground-reflected horizontal solar irradiance in W/m2.
altitude – The altitude of the sun in degrees [0-90].
sharp – A number between 0 and 180 representing the solar horizontal angle relative to front of person (SHARP). 0 signifies sun that is shining directly into the person’s face and 180 signifies sun that is shining at the person’s back. Default is 135, assuming that a person typically faces their side or back to the sun to avoid glare.
fract_exposed – A number between 0 and 1 representing the fraction of the body exposed to direct sunlight. Note that this does not include the body’s self-shading; only the shading from surroundings. Default is 1 for a person standing in an open area.
posture – A text string indicating the posture of the body. Letters must be lowercase. Choose from the following: “standing”, “seated”, “supine”. Default is “standing”.
- ladybug_comfort.solarcal.body_solar_flux_from_horiz_solar(diff_horiz_solar, dir_horiz_solar, altitude, sharp=135, fract_exposed=1, floor_reflectance=0.25, posture='standing')[source]¶
Estimate total solar flux on human geometry from horizontal solar components.
This method is useful for cases when one wants to take the hourly results of a spatial radiation study with Radiance and use them to build a map of ERF or MRT delta on a person.
- Parameters:
diff_horiz_solar – Diffuse horizontal solar irradiance in W/m2.
dir_horiz_solar – Direct horizontal solar irradiance in W/m2.
altitude – The altitude of the sun in degrees [0-90].
sharp – A number between 0 and 180 representing the solar horizontal angle relative to front of person (SHARP). 0 signifies sun that is shining directly into the person’s face and 180 signifies sun that is shining at the person’s back. Default is 135, assuming that a person typically faces their side or back to the sun to avoid glare.
fract_exposed – A number between 0 and 1 representing the fraction of the body exposed to direct sunlight. Note that this does not include the body’s self-shading; only the shading from surroundings. Default is 1 for a person standing in an open area.
floor_reflectance – A number between 0 and 1 the represents the reflectance of the floor. Default is for 0.25 which is characteristic of outdoor grass or dry bare soil.
posture – A text string indicating the posture of the body. Letters must be lowercase. Choose from the following: “standing”, “seated”, “supine”. Default is “standing”.
- ladybug_comfort.solarcal.body_solar_flux_from_parts(diff_horiz_solar, dir_normal_solar, altitude, sharp=135, sky_exposure=1, fract_exposed=1, floor_reflectance=0.25, posture='standing')[source]¶
Estimate the total solar flux on human geometry from solar components.
- Parameters:
diff_horiz_solar – Diffuse horizontal solar irradiance in W/m2.
dir_normal_solar – Direct normal solar irradiance in W/m2.
altitude – The altitude of the sun in degrees [0-90].
sharp – A number between 0 and 180 representing the solar horizontal angle relative to front of person (SHARP). 0 signifies sun that is shining directly into the person’s face and 180 signifies sun that is shining at the person’s back. Default is 135, assuming that a person typically faces their side or back to the sun to avoid glare.
sky_exposure – A number between 0 and 1 representing the fraction of the sky vault in occupant’s view. Default is 1 for outdoors in an open field.
fract_exposed – A number between 0 and 1 representing the fraction of the body exposed to direct sunlight. Note that this does not include the body’s self-shading; only the shading from surroundings. Default is 1 for a person standing in an open area.
floor_reflectance – A number between 0 and 1 the represents the reflectance of the floor. Default is for 0.25 which is characteristic of outdoor grass or dry bare soil.
posture – A text string indicating the posture of the body. Letters must be lowercase. Choose from the following: “standing”, “seated”, “supine”. Default is “standing”.
- ladybug_comfort.solarcal.erf_from_body_solar_flux(solar_flux, body_absorptivity=0.7, body_emissivity=0.95)[source]¶
Calculate effective radiant field (ERF) from incident solar flux on body in W/m2.
- Parameters:
solar_flux – A number for the average solar flux over the human body in W/m2.
body_absorptivity – A number between 0 and 1 representing the average shortwave absorptivity of the body (including clothing and skin color). Typical clothing values - white: 0.2, khaki: 0.57, black: 0.88 Typical skin values - white: 0.57, brown: 0.65, black: 0.84 Default is 0.7 for average (brown) skin and medium clothing.
body_emissivity – A number between 0 and 1 representing the average longwave emissivity of the body. Default is 0.95, which is almost always the case except in rare situations of wearing metallic clothing.
- ladybug_comfort.solarcal.erf_from_mrt_delta(mrt_delta, fract_efficiency=0.725, rad_trans_coeff=6.012)[source]¶
Calculate the effective radiant field (ERF) from a MRT delta.
- Parameters:
mrt_delta – A mean radiant temperature (MRT) delta in Kelvin or degrees Celsius.
fract_efficiency – A number representing the fraction of the body surface exposed to radiation from the environment. This is typically either 0.725 for a standing or supine person or 0.696 for a seated person. Default is 0.725 for a standing person.
rad_trans_coeff – A number representing the radiant heat transfer coefficient in (W/m2-K). Default is 6.012, which is almost always the case.
- ladybug_comfort.solarcal.get_projection_factor(altitude, sharp=135, posture='standing')[source]¶
Get the fraction of body surface area exposed to direct sun from solar position.
This is effectively Ap / Ad in the original Solarcal equations.
- Parameters:
altitude – A number between 0 and 90 representing the altitude of the sun in degrees.
sharp – A number between 0 and 180 representing the solar horizontal angle relative to front of person (SHARP). 0 signifies sun that is shining directly into the person’s face and 180 signifies sun that is shining at the person’s back. Default is 135, assuming that a person typically faces their side or back to the sun to avoid glare.
posture – A text string indicating the posture of the body. Letters must be lowercase. Choose from the following: “standing”, “seated”, “supine”. Default is “standing”.
- ladybug_comfort.solarcal.get_projection_factor_simple(altitude, sharp=135, posture='standing')[source]¶
Get the fraction of body surface area exposed to direct sun using a simpler method.
This is effectively Ap / Ad in the original Solarcal equations.
This is a more portable version of the get_projection_area() function since it does not rely on the large matrix of projection factors stored externally in csv files. However, it is less precise since it effectively interpolates over the missing parts of the matrix. So this is only recommended for cases where such csv files are missing.
- Parameters:
altitude – A number between 0 and 90 representing the altitude of the sun in degrees.
sharp – A number between 0 and 180 representing the solar horizontal angle relative to front of person (SHARP). Default is 135, assuming a person typically faces their side or back to the sun to avoid glare.
posture – A text string indicating the posture of the body. Letters must be lowercase. Choose from the following: “standing”, “seated”, “supine”. Default is “standing”.
- ladybug_comfort.solarcal.indoor_sky_heat_exch(longwave_mrt, diff_horiz_solar, dir_normal_solar, alt, sky_exposure=1, fract_exposed=1, floor_reflectance=0.25, window_transmittance=0.4, posture='seated', sharp=135, body_absorptivity=0.7, body_emissivity=0.95)[source]¶
Perform a full indoor sky radiant heat exchange.
- Parameters:
longwave_mrt – The longwave mean radiant temperature (MRT) expereinced as a result of indoor surface temperatures in C.
diff_horiz_solar – Diffuse horizontal solar irradiance in W/m2.
dir_normal_solar – Direct normal solar irradiance in W/m2.
alt – The altitude of the sun in degrees [0-90].
sky_exposure – A number between 0 and 1 representing the fraction of the sky vault in occupant’s view. Default is 1 for a completely glass box.
fract_exposed – A number between 0 and 1 representing the fraction of the body exposed to direct sunlight. Note that this does not include the body’s self-shading; only the shading from surroundings. Default is 1 for a person standing in an open area.
floor_reflectance – A number between 0 and 1 the represents the reflectance of the floor. Default is for 0.25 which is characteristic of outdoor grass or dry bare soil.
window_transmittance – A number between 0 and 1 that represents the broadband solar transmittance of the window through which the sun is coming. Such values tend to be slightly less than the SHGC. Values might be as low as 0.2 and could be as high as 0.85 for a single pane of glass. Default is 0.4 assuming a double pane window with a relatively mild low-e coating.
posture – A text string indicating the posture of the body. Letters must be lowercase. Choose from the following: “standing”, “seated”, “supine”. Default is “standing”.
sharp – A number between 0 and 180 representing the solar horizontal angle relative to front of person (SHARP). 0 signifies sun that is shining directly into the person’s face and 180 signifies sun that is shining at the person’s back. Default is 135, assuming that a person typically faces their side or back to the sun to avoid glare.
body_absorptivity – A number between 0 and 1 representing the average shortwave absorptivity of the body (including clothing and skin color). Typical clothing values - white: 0.2, khaki: 0.57, black: 0.88 Typical skin values - white: 0.57, brown: 0.65, black: 0.84 Default is 0.7 for average (brown) skin and medium clothing.
body_emissivity – A number between 0 and 1 representing the average longwave emissivity of the body. Default is 0.95, which is almost always the case except in rare situations of wearing metallic clothing.
- Returns:
A dictionary containing results with the following keys
erf : The shortwave effective radiant field (ERF) in W/m2.
dmrt : The MRT delta as a result of shortwave irradiance in C.
mrt: The final MRT expereinced as a result of sky heat exchange in C.
- ladybug_comfort.solarcal.longwave_mrt_delta_from_horiz_ir(horiz_ir, srfs_temp, sky_exposure=1, body_emissivity=0.95)[source]¶
Calculate the MRT delta as a result of longwave radiant exchange with the sky.
Note that this value is typically negative since the earth (and humans) tend to radiate heat out to space in the longwave portion of the spectrum.
- Parameters:
horiz_ir – A float value that represents the downwelling horizontal infrared radiation intensity in W/m2.
srfs_temp – The temperature of surfaces around the person in degrees Celsius. This includes the ground and any other surfaces blocking the view to the sky. Typically, the dry bulb temperature is used when such surface temperatures are unknown.
sky_exposure – A number between 0 and 1 representing the fraction of the sky vault in occupant’s view. Default is 1 for outdoors in an open field.
- ladybug_comfort.solarcal.longwave_mrt_delta_from_sky_temp(sky_temp, srfs_temp, sky_exposure=1)[source]¶
Calculate the MRT delta as a result of longwave radiant exchange with the sky.
Note that this value is typically negative since the earth (and humans) tend to radiate heat out to space in the longwave portion of the spectrum.
- Parameters:
sky_temp – The sky temperature in degrees Celsius.
srfs_temp – The temperature of surfaces around the person in degrees Celsius. This includes the ground and any other surfaces blocking the view to the sky. Typically, the dry bulb temperature is used when such surface temperatures are unknown.
sky_exposure – A number between 0 and 1 representing the fraction of the sky vault in occupant’s view. Default is 1 for outdoors in an open field.
- ladybug_comfort.solarcal.mrt_delta_from_erf(erf, fract_efficiency=0.725, rad_trans_coeff=6.012)[source]¶
Calculate the mean radiant temperature (MRT) delta as a result of an ERF.
- Parameters:
erf – A number representing the effective radiant field (ERF) on the person in W/m2.
fract_efficiency – A number representing the fraction of the body surface exposed to radiation from the environment. This is typically either 0.725 for a standing or supine person or 0.696 for a seated person. Default is 0.725 for a standing person.
rad_trans_coeff – A number representing the radiant heat transfer coefficient in (W/m2-K). Default is 6.012, which is almost always the case.
- ladybug_comfort.solarcal.outdoor_sky_heat_exch(srfs_temp, horiz_ir, diff_horiz_solar, dir_normal_solar, alt, sky_exposure=1, fract_exposed=1, floor_reflectance=0.25, posture='standing', sharp=135, body_absorptivity=0.7, body_emissivity=0.95)[source]¶
Perform a full outdoor sky radiant heat exchange.
- Parameters:
srfs_temp – The temperature of surfaces around the person in degrees Celsius. This includes the ground and any other surfaces blocking the view to the sky. When the temperature of these individual surfaces are known, the input here should be the average temperature of the surfaces weighted by view-factor to the human. When such individual surface temperatures are unknown, the outdoor dry bulb temperature is typically used as a proxy.
horiz_ir – The horizontal infrared radiation intensity from the sky in W/m2.
diff_horiz_solar – Diffuse horizontal solar irradiance in W/m2.
dir_normal_solar – Direct normal solar irradiance in W/m2.
alt – The altitude of the sun in degrees [0-90].
sky_exposure – A number between 0 and 1 representing the fraction of the sky vault in occupant’s view. Default is 1 for outdoors in an open field.
fract_exposed – A number between 0 and 1 representing the fraction of the body exposed to direct sunlight. Note that this does not include the body’s self-shading; only the shading from surroundings. Default is 1 for a person standing in an open area.
floor_reflectance – A number between 0 and 1 the represents the reflectance of the floor. Default is for 0.25 which is characteristic of outdoor grass or dry bare soil.
posture – A text string indicating the posture of the body. Letters must be lowercase. Choose from the following: “standing”, “seated”, “supine”. Default is “standing”.
sharp – A number between 0 and 180 representing the solar horizontal angle relative to front of person (SHARP). 0 signifies sun that is shining directly into the person’s face and 180 signifies sun that is shining at the person’s back. Default is 135, assuming that a person typically faces their side or back to the sun to avoid glare.
body_absorptivity – A number between 0 and 1 representing the average shortwave absorptivity of the body (including clothing and skin color). Typical clothing values - white: 0.2, khaki: 0.57, black: 0.88 Typical skin values - white: 0.57, brown: 0.65, black: 0.84 Default is 0.7 for average (brown) skin and medium clothing.
body_emissivity – A number between 0 and 1 representing the average longwave emissivity of the body. Default is 0.95, which is almost always the case except in rare situations of wearing metallic clothing.
- Returns:
A dictionary containing results with the following keys
s_erf : The shortwave effective radiant field (ERF) in W/m2.
s_dmrt : The MRT delta as a result of shortwave irradiance in C.
l_erf : The longwave effective radiant field (ERF) in W/m2.
l_dmrt : The MRT delta as a result of longwave sky exchange in C.
mrt: The final MRT expereinced as a result of sky heat exchange in C.
- ladybug_comfort.solarcal.sharp_from_solar_and_body_azimuth(solar_azimuth, body_azimuth=0)[source]¶
Calculate solar horizontal angle relative to front of person (SHARP).
- Parameters:
solar_azimuth – A number between 0 and 360 representing the solar azimuth in degrees (0=North, 90=East, 180=South, 270=West).
body_azimuth – A number between 0 and 360 representing the direction that the human is facing in degrees (0=North, 90=East, 180=South, 270=West).
- ladybug_comfort.solarcal.shortwave_from_horiz_components(longwave_mrt, diff_horiz_solar, dir_horiz_solar, ref_horiz_solar, alt, fract_exposed=1, posture='standing', sharp=135, body_absorptivity=0.7, body_emissivity=0.95)[source]¶
Perform shortwave radiant heat exchange using horizontal components.
This is useful when building a map of MRT using the direct, diffuse, and ground reflected results of a Radiance study instead of the solar components directly from an EPW or Wea file. Note that all input radiation components should already account for the amount of sky seen and solar heat reflections off of surfaces.
- Parameters:
longwave_mrt – The longwave mean radiant temperature (MRT) expereinced as a result of indoor surface temperatures in C.
diff_horiz_solar – Diffuse horizontal solar irradiance in W/m2.
dir_horiz_solar – Direct horizontal solar irradiance in W/m2.
ref_horiz_solar – Ground-reflected horizontal irradiance in W/m2.
alt – The altitude of the sun in degrees [0-90].
fract_exposed – A number between 0 and 1 representing the fraction of the body exposed to direct sunlight. Note that this does not include the body’s self-shading; only the shading from surroundings. Default is 1 for a person standing in an open area.
posture – A text string indicating the posture of the body. Letters must be lowercase. Choose from the following: “standing”, “seated”, “supine”. Default is “standing”.
sharp – A number between 0 and 180 representing the solar horizontal angle relative to front of person (SHARP). 0 signifies sun that is shining directly into the person’s face and 180 signifies sun that is shining at the person’s back. Default is 135, assuming that a person typically faces their side or back to the sun to avoid glare.
body_absorptivity – A number between 0 and 1 representing the average shortwave absorptivity of the body (including clothing and skin color). Typical clothing values - white: 0.2, khaki: 0.57, black: 0.88 Typical skin values - white: 0.57, brown: 0.65, black: 0.84 Default is 0.7 for average (brown) skin and medium clothing.
body_emissivity – A number between 0 and 1 representing the average longwave emissivity of the body. Default is 0.95, which is almost always the case except in rare situations of wearing metallic clothing.
- Returns:
A dictionary containing results with the following keys
erf : The shortwave effective radiant field (ERF) in W/m2.
dmrt : The MRT delta as a result of shortwave irradiance in C.
mrt: The final MRT expereinced as a result of sky heat exchange in C.
- ladybug_comfort.solarcal.shortwave_from_horiz_solar(longwave_mrt, diff_horiz_solar, dir_horiz_solar, alt, fract_exposed=1, floor_reflectance=0.25, posture='standing', sharp=135, body_absorptivity=0.7, body_emissivity=0.95)[source]¶
Perform shortwave radiant heat exchange using horizontal solar components.
This is useful when building a map of MRT using the direct and diffuse results of a Radiance study instead of the solar components directly from an EPW or Wea file. Note that all input radiation components should already account for the amount of sky seen and solar heat reflections off of surfaces.
- Parameters:
longwave_mrt – The longwave mean radiant temperature (MRT) expereinced as a result of indoor surface temperatures in C.
diff_horiz_solar – Diffuse horizontal solar irradiance in W/m2.
dir_horiz_solar – Direct horizontal solar irradiance in W/m2.
alt – The altitude of the sun in degrees [0-90].
fract_exposed – A number between 0 and 1 representing the fraction of the body exposed to direct sunlight. Note that this does not include the body’s self-shading; only the shading from surroundings. Default is 1 for a person standing in an open area.
floor_reflectance – A number between 0 and 1 the represents the reflectance of the floor. Default is for 0.25 which is characteristic of outdoor grass or dry bare soil.
posture – A text string indicating the posture of the body. Letters must be lowercase. Choose from the following: “standing”, “seated”, “supine”. Default is “standing”.
sharp – A number between 0 and 180 representing the solar horizontal angle relative to front of person (SHARP). 0 signifies sun that is shining directly into the person’s face and 180 signifies sun that is shining at the person’s back. Default is 135, assuming that a person typically faces their side or back to the sun to avoid glare.
body_absorptivity – A number between 0 and 1 representing the average shortwave absorptivity of the body (including clothing and skin color). Typical clothing values - white: 0.2, khaki: 0.57, black: 0.88 Typical skin values - white: 0.57, brown: 0.65, black: 0.84 Default is 0.7 for average (brown) skin and medium clothing.
body_emissivity – A number between 0 and 1 representing the average longwave emissivity of the body. Default is 0.95, which is almost always the case except in rare situations of wearing metallic clothing.
- Returns:
A dictionary containing results with the following keys
erf : The shortwave effective radiant field (ERF) in W/m2.
dmrt : The MRT delta as a result of shortwave irradiance in C.
mrt: The final MRT expereinced as a result of sky heat exchange in C.