ladybug.skymodel module

ladybug.skymodel.ashrae_clear_sky(altitudes, month, sky_clearness=1)

Calculate solar flux for an original ASHRAE Clear Sky.

Note

[1] American Society of Heating Refrigerating and Air-Conditioning Engineers. 2005. 2005 ASHRAE Handbook: Fundamentals. Atlanta, GA. Chapter 31.

Parameters

• altitudes – A list of solar altitudes in degrees

• month – An integer (1-12) indicating the month the altitudes belong to

• 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.

Returns

A tuple with two elements

• dir_norm_rad: A list of direct normal radiation values for each of the connected altitudes in W/m2.

• dif_horiz_rad: A list of diffuse horizontal radiation values for each of the connected altitudes in W/m2.

ladybug.skymodel.ashrae_revised_clear_sky(altitudes, tb, td, use_2017_model=False)

Calculate solar flux for an ASHRAE Revised Clear Sky (“Tau Model”).

Note

[1] American Society of Heating, Refrigerating and Air-Conditioning Engineers. 2009. 2009 Ashrae Handbook: Fundamentals. Atlanta, GA.

Parameters

• altitudes – A list of solar altitudes in degrees.

• tb – A value indicating the beam optical depth of the sky.

• td – A value indicating the diffuse optical depth of the sky.

• use_2017_model – Set to True to use coefficients associated with the new version of the Tau model released in the 2013 and 2017 HOF. Note that the correct use of the new version requires updated tb and td values. At present, all .stat files distributed by the US DoE are using the older (2009) values for tb and td and so this input defaults to False.

Returns

A tuple with two elements

• dir_norm_rad: A list of direct normal radiation values for each of the connected altitudes in W/m2.

• dif_horiz_rad: A list of diffuse horizontally radiation values for each of the connected altitudes in W/m2.

ladybug.skymodel.calc_horizontal_infrared(sky_cover, dry_bulb, dew_point)

Calculate horizontal infrared radiation intensity.

See EnergyPlus Engineering Reference for more information: https://bigladdersoftware.com/epx/docs/8-9/engineering-reference/climate-calculations.html#sky-radiation-modeling

Note

[1] Walton, G. N. 1983. Thermal Analysis Research Program Reference Manual. NBSSIR 83-2655. National Bureau of Standards, p. 21.

[2] Clark, G. and C. Allen, “The Estimation of Atmospheric Radiation for Clear and Cloudy Skies,” Proceedings 2nd National Passive Solar Conference (AS/ISES), 1978, pp. 675-678.

Parameters

• sky_cover – A float value between 0 and 10 that represents the opaque sky cover in tenths (0 = clear; 10 = completely overcast)

• dry_bulb – A float value that represents the dry bulb temperature in degrees C.

• dew_point – A float value that represents the dew point temperature in degrees C.

Returns

horiz_ir – A horizontal infrared radiation intensity value in W/m2.

ladybug.skymodel.calc_sky_temperature(horiz_ir, source_emissivity=1)

Calculate sky temperature in Celsius.

See EnergyPlus Engineering Reference for more information: https://bigladdersoftware.com/epx/docs/8-9/engineering-reference/ climate-calculations.html#energyplus-sky-temperature-calculation

Parameters

• horiz_ir – A float value that represents horizontal infrared radiation intensity in W/m2.

• source_emissivity – A float value between 0 and 1 indicating the emissivity of the heat source that is radiating to the sky. Default is 1 for most outdoor surfaces.

Returns

sky_temp – A sky temperature value in C.

ladybug.skymodel.clearness_index(ghi, altitude, extra_radiation, min_sin_altitude=0.065, max_clearness_index=2.0)

Calculate the clearness index.

The clearness index is the ratio of global to extraterrestrial irradiance on a horizontal plane.

Note

[1] Maxwell, E. L., “A Quasi-Physical Model for Converting Hourly Global Horizontal to Direct Normal Insolation”, Technical Report No. SERI/TR-215-3087, Golden, CO: Solar Energy Research Institute, 1987.

Parameters

• ghi – numeric Global horizontal irradiance in W/m^2.

• altitude – numeric True (not refraction-corrected) solar altitude angle in decimal degrees.

• extra_radiation – numeric Irradiance incident at the top of the atmosphere

• min_sin_altitude – numeric, default 0.065 Minimum value of sin(altitude) to allow when calculating global clearness index kt. Equivalent to altitude = 3.727 degrees.

• max_clearness_index – numeric, default 2.0 Maximum value of the clearness index. The default, 2.0, allows for over-irradiance events typically seen in sub-hourly data. NREL’s SRRL Fortran code used 0.82 for hourly data.

Returns

kt – numeric. Clearness index

ladybug.skymodel.clearness_index_zenith_independent(clearness_index, airmass, max_clearness_index=2.0)

Calculate the zenith angle independent clearness index.

Note

[1] Perez, R., P. Ineichen, E. Maxwell, R. Seals and A. Zelenka, (1992). “Dynamic Global-to-Direct Irradiance Conversion Models”. ASHRAE Transactions-Research Series, pp. 354-369

Parameters

• clearness_index – numeric. Ratio of global to extraterrestrial irradiance on a horizontal plane

• airmass – numeric Airmass

• max_clearness_index – numeric, default 2.0 Maximum value of the clearness index. The default, 2.0, allows for over-irradiance events typically seen in sub-hourly data. NREL’s SRRL Fortran code used 0.82 for hourly data.

Returns

kt_prime – numeric. Zenith independent clearness index

ladybug.skymodel.dirint(ghi, altitudes, doys, pressures, use_delta_kt_prime=True, temp_dew=None, min_sin_altitude=0.065, min_altitude=3)

Determine DNI from GHI using the DIRINT modification of the DISC model.

Implements the modified DISC model known as “DIRINT” introduced in [1]. DIRINT predicts direct normal irradiance (DNI) from measured global horizontal irradiance (GHI). DIRINT improves upon the DISC model by using time-series GHI data and dew point temperature information. The effectiveness of the DIRINT model improves with each piece of information provided.

The pvlib implementation limits the clearness index to 1. The DIRINT model requires time series data.

Note

[1] Perez, R., P. Ineichen, E. Maxwell, R. Seals and A. Zelenka, (1992). “Dynamic Global-to-Direct Irradiance Conversion Models”. ASHRAE Transactions-Research Series, pp. 354-369

[2] Maxwell, E. L., “A Quasi-Physical Model for Converting Hourly Global Horizontal to Direct Normal Insolation”, Technical Report No. SERI/TR-215-3087, Golden, CO: Solar Energy Research Institute, 1987.

Parameters

• ghi – array-like Global horizontal irradiance in W/m^2.

• altitudes – array-like True (not refraction-corrected) solar altitude angles in decimal degrees.

• doys – array-like Integers representing the day of the year.

• pressures – array-like The site pressure in Pascal. Pressure may be measured or an average pressure may be calculated from site altitude.

• use_delta_kt_prime – bool, default True If True, indicates that the stability index delta_kt_prime is included in the model. The stability index adjusts the estimated DNI in response to dynamics in the time series of GHI. It is recommended that delta_kt_prime is not used if the time between GHI points is 1.5 hours or greater. If use_delta_kt_prime=True, input data must be Series.

• temp_dew – None or array-like, default None Surface dew point temperatures, in degrees C. Values of temp_dew must be numeric. If temp_dew is not provided, then dew point improvements are not applied.

• min_sin_altitude – numeric, default 0.065 Minimum value of sin(altitude) to allow when calculating global clearness index kt. Equivalent to altitude = 3.727 degrees.

• min_altitude – numeric, default 87 Minimum value of altitude to allow in DNI calculation. DNI will be set to 0 for times with altitude values smaller than min_altitude.

Returns

dni – array-like. The modeled direct normal irradiance in W/m^2 provided by the DIRINT model.

ladybug.skymodel.disc(ghi, altitude, doy, pressure=101325, min_sin_altitude=0.065, min_altitude=3, max_airmass=12)

Estimate Direct Normal Irradiance from Global Horizontal Irradiance using the DISC model.

The DISC algorithm converts global horizontal irradiance to direct normal irradiance through empirical relationships between the global and direct clearness indices.

This implementation limits the clearness index to 1 by default.

The original report describing the DISC model [1] uses the relative air mass rather than the absolute (pressure-corrected) air mass. However, the NREL implementation of the DISC model [2] uses absolute air mass. PVLib Matlab also uses the absolute air mass. pvlib python defaults to absolute air mass, but the relative airmass can be used by supplying pressure=None.

Note

[1] Maxwell, E. L., “A Quasi-Physical Model for Converting Hourly Global Horizontal to Direct Normal Insolation”, Technical Report No. SERI/TR-215-3087, Golden, CO: Solar Energy Research Institute, 1987.

[2] Maxwell, E. “DISC Model”, Excel Worksheet. https://www.nrel.gov/grid/solar-resource/disc.html

Parameters

• ghi – numeric Global horizontal irradiance in W/m^2.

• altitude – numeric True (not refraction-corrected) solar altitude angles in decimal degrees.

• doy – An integer representing the day of the year.

• pressure – None or numeric, default 101325 Site pressure in Pascal. If None, relative air mass is used instead of absolute (pressure-corrected) air mass.

• min_sin_altitude – numeric, default 0.065 Minimum value of sin(altitude) to allow when calculating global clearness index kt. Equivalent to altitude = 3.727 degrees.

• min_altitude – numeric, default 87 Minimum value of altitude to allow in DNI calculation. DNI will be set to 0 for times with altitude values smaller than min_altitude.

• max_airmass – numeric, default 12 Maximum value of the air mass to allow in Kn calculation. Default value (12) comes from range over which Kn was fit to air mass in the original paper.

Returns

A tuple with two elements

• dni: The modeled direct normal irradiance in W/m^2 provided by the Direct Insolation Simulation Code (DISC) model.

• kt: Ratio of global to extraterrestrial irradiance on a horizontal plane.

• am: Airmass

ladybug.skymodel.estimate_illuminance_from_irradiance(altitude, ghi, dni, dhi, dew_point, rel_airmass=None)

Estimate sky illuminance components from irradiance components.

This function uses actual zenith rather than apparent zenith.

Note

[1] Perez R. (1990). ‘Modeling Daylight Availability and Irradiance Components from Direct and Global Irradiance’. Solar Energy. Vol. 44. No. 5, pp. 271-289. USA.

Parameters

• altitude – Solar altitude angle in degrees.

• ghi – Number for Global Horizontal Irradiance in W/m2.

• dni – Number for Direct Normal Irradiance in W/m2.

• dhi – Number for Diffuse Horizontal Irradiance in W/m2.

• dew_point – Surface dewpoint in degrees C.

• rel_airmass – A number between 1 and ~38 representing the ratio of air mass between the sun and the observer and the air mass that is directly above the observer. Default is None, which will simply use the input solar altitude and the get_relative_airmass function in this module with the kastenyoung1989 model to compute this value.

Returns

A tuple with four elements

• gh_ill: Value for Global Horizontal Illuminance in lux.

• dn_ill: Value for Direct Normal Illuminance in lux.

• dh_ill: Value for Diffuse Horizontal Illuminance in lux.

• z_lum: Value for Zenith Luminance in lux.

ladybug.skymodel.get_absolute_airmass(airmass_relative, pressure=101325.0)

Determine absolute (pressure corrected) airmass from relative airmass and atmospheric pressure.

Gives the airmass for locations not at sea-level (i.e. not at standard pressure). The input argument airmass_relative is the relative air mass. The input argument pressure is the pressure (in Pascals) at the location of interest and must be greater than 0. The calculation for absolute air mass is absolute airmass = (relative airmass)*pressure/101325

Note

[1] C. Gueymard, “Critical analysis and performance assessment of clear sky solar irradiance models using theoretical and measured data,” Solar Energy, vol. 51, pp. 121-138, 1993.

Parameters

• airmass_relative – numeric. The air mass at sea-level.

• pressure – numeric, default 101325 The site pressure in Pascal.

Returns

airmass_absolute – numeric. Absolute (pressure corrected) air mass

ladybug.skymodel.get_extra_radiation(doy, solar_constant=1366.1)

Determine extraterrestrial radiation from day of year (using the spencer method).

Note

[1] M. Reno, C. Hansen, and J. Stein, “Global Horizontal Irradiance Clear Sky Models: Implementation and Analysis”, Sandia National Laboratories, SAND2012-2389, 2012.

[2] <http://solardat.uoregon.edu/SolarRadiationBasics.html>, Eqs. SR1 and SR2

Parameters

• doy – array of integers representing the days of the year.

• solar_constant – float, default 1366.1 The solar constant.

Returns

dni_extra – float, array, or Series. The extraterrestrial radiation present in watts per square meter on a surface which is normal to the sun. Pandas Timestamp and DatetimeIndex inputs will yield a Pandas TimeSeries. All other inputs will yield a float or an array of floats.

ladybug.skymodel.get_relative_airmass(altitude, model='kastenyoung1989')

Gives the relative (not pressure-corrected) airmass.

Gives the airmass at sea-level when given a sun altitude angle (in degrees). The model variable allows selection of different airmass models (described below). If model is not included or is not valid, the default model is ‘kastenyoung1989’.

Note

[1] Fritz Kasten. “A New Table and Approximation Formula for the Relative Optical Air Mass”. Technical Report 136, Hanover, N.H.: U.S. Army Material Command, CRREL. [2] A. T. Young and W. M. Irvine, “Multicolor Photoelectric Photometry of the Brighter Planets,” The Astronomical Journal, vol. 72, pp. 945-950, 1967. [3] Fritz Kasten and Andrew Young. “Revised optical air mass tables and approximation formula”. Applied Optics 28:4735-4738 [4] C. Gueymard, “Critical analysis and performance assessment of clear sky solar irradiance models using theoretical and measured data,” Solar Energy, vol. 51, pp. 121-138, 1993. [5] A. T. Young, “AIR-MASS AND REFRACTION,” Applied Optics, vol. 33, pp. 1108-1110, Feb 1994. [6] Keith A. Pickering. “The Ancient Star Catalog”. DIO 12:1, 20, [7] Matthew J. Reno, Clifford W. Hansen and Joshua S. Stein, “Global Horizontal Irradiance Clear Sky Models: Implementation and Analysis” Sandia Report, (2012).

Parameters

• altitude – numeric Altitude angle of the sun in degrees. Note that some models use the apparent (refraction corrected) altitude angle, and some models use the true (not refraction-corrected) altitude angle. See model descriptions to determine which type of altitude angle is required. Apparent altitude angles must be calculated at sea level.

• model –

  string, default ‘kastenyoung1989’

  Available models include the following:

  • ’simple’ - secant(apparent altitude angle) - Note that this gives -inf at altitude=0

  • ’kasten1966’ - See reference [1] - requires apparent sun altitude

  • ’youngirvine1967’ - See reference [2] - requires true sun altitude

  • ’kastenyoung1989’ - See reference [3] - requires apparent sun altitude

  • ’gueymard1993’ - See reference [4] - requires apparent sun altitude

  • ’young1994’ - See reference [5] - requires true sun altitude

  • ’pickering2002’ - See reference [6] - requires apparent sun altitude

Returns

airmass_relative – Relative airmass at sea level. Will return None for any altitude angle smaller than 0 degrees.

ladybug.skymodel.zhang_huang_solar(alt, cloud_cover, relative_humidity, dry_bulb_present, dry_bulb_t3_hrs, wind_speed, irr_0=1355)

Calculate global horizontal solar irradiance using the Zhang-Huang model.

Note

[1] Zhang, Q.Y. and Huang, Y.J. 2002. “Development of typical year weather files for Chinese locations”, LBNL-51436, ASHRAE Transactions, Vol. 108, Part 2.

Parameters

• alt – A solar altitude in degrees.

• cloud_cover – A float value between 0 and 10 that represents the sky cloud cover in tenths (0 = clear; 10 = completely overcast)

• relative_humidity – A float value between 0 and 100 that represents the relative humidity in percent.

• dry_bulb_present – A float value that represents the dry bulb temperature at the time of interest (in degrees C).

• dry_bulb_t3_hrs – A float value that represents the dry bulb temperature at three hours before the time of interest (in degrees C).

• wind_speed – A float value that represents the wind speed in m/s.

• constant (irr_0 = Optional extraterrestrial solar) – Default is to use the average value over the earth’s orbit (1355).

Returns

glob_ir – A global horizontall radiation value in W/m2.

ladybug.skymodel.zhang_huang_solar_split(altitudes, doys, cloud_cover, relative_humidity, dry_bulb_present, dry_bulb_t3_hrs, wind_speed, atm_pressure, use_disc=False)

Calculate direct and diffuse solar irradiance using the Zhang-Huang model.

By default, this function uses the DIRINT method (aka. Perez split) to split global irradiance into direct and diffuse. This is the same method used by EnergyPlus.

Parameters

• altitudes – A list of solar altitudes in degrees.

• doys – A list of days of the year that correspond to the altitudes.

• cloud_cover – A list of float values between 0 and 10 that represents cloud cover in tenths (0 = clear; 10 = completely overcast)

• relative_humidity – A list of float values between 0 and 100 that represents the relative humidity in percent.

• dry_bulb_present – A list of float values that represents the dry bulb temperature at the time of interest (in degrees C).

• dry_bulb_t3_hrs – A list of float values that represents the dry bulb temperature at three hours before the time of interest (in degrees C).

• wind_speed – A list of float values that represents the wind speed in m/s.

• atm_pressure – A list of float values that represent the atmospheric pressure in Pa.

• use_disc – Set to True to use the original DISC model as opposed to the newer and more accurate DIRINT model. Default: False.

Returns

A tuple with two elements

• dir_norm_rad: A list of direct normal radiation values for each of the connected altitudes in W/m2.

• dif_horiz_rad: A list of diffuse horizontall radiation values for each of the connected altitudes in W/m2.