diff --git a/docs/sphinx/source/whatsnew/v0.11.1.rst b/docs/sphinx/source/whatsnew/v0.11.1.rst index 1e59182092..21529e2b14 100644 --- a/docs/sphinx/source/whatsnew/v0.11.1.rst +++ b/docs/sphinx/source/whatsnew/v0.11.1.rst @@ -50,16 +50,16 @@ Documentation * Added gallery example demonstrating the application of several spectral mismatch factor models. (:issue:`2107`, :pull:`2114`) - * Added gallery example on calculating cell temperature for floating PV. (:pull:`2110`) - * Added gallery example demonstrating how to use different Perez coefficients in a ModelChain. (:issue:`2127`, :pull:`2148`) * Fixed examples in :py:func:`pvlib.shading.shaded_fraction1d`. (:pull:`#2215`) * Removed unused "times" input from dni_et() function (:issue:`2105`) +* Updated :py:func:`pvlib.irradiance.haydavies` to include equation variable + definitions and a new "notes" section (:issue:`2183`, :pull:`2191`) * Split the contributing page into several pages (:issue:`2210`, :pull:`2219`) diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index 3b9c5cd0c0..77f9ead91f 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -463,15 +463,15 @@ def poa_components(aoi, dni, poa_sky_diffuse, poa_ground_diffuse): surface, from :func:`aoi`. dni : numeric - Direct normal irradiance (W/m^2), as measured from a TMY file or + Direct normal irradiance (Wm⁻²), as measured from a TMY file or calculated with a clearsky model. poa_sky_diffuse : numeric - Diffuse irradiance (W/m^2) in the plane of the modules, as + Diffuse irradiance (Wm⁻²) in the plane of the modules, as calculated by a diffuse irradiance translation function poa_ground_diffuse : numeric - Ground reflected irradiance (W/m^2) in the plane of the modules, + Ground reflected irradiance (Wm⁻²) in the plane of the modules, as calculated by an albedo model (eg. :func:`grounddiffuse`) Returns @@ -479,12 +479,12 @@ def poa_components(aoi, dni, poa_sky_diffuse, poa_ground_diffuse): irrads : OrderedDict or DataFrame Contains the following keys: - * ``poa_global`` : Total in-plane irradiance (W/m^2) - * ``poa_direct`` : Total in-plane beam irradiance (W/m^2) - * ``poa_diffuse`` : Total in-plane diffuse irradiance (W/m^2) - * ``poa_sky_diffuse`` : In-plane diffuse irradiance from sky (W/m^2) + * ``poa_global`` : Total in-plane irradiance (Wm⁻²) + * ``poa_direct`` : Total in-plane beam irradiance (Wm⁻²) + * ``poa_diffuse`` : Total in-plane diffuse irradiance (Wm⁻²) + * ``poa_sky_diffuse`` : In-plane diffuse irradiance from sky (Wm⁻²) * ``poa_ground_diffuse`` : In-plane diffuse irradiance from ground - (W/m^2) + (Wm⁻²) Notes ------ @@ -529,7 +529,7 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None): (e.g. surface facing up = 0, surface facing horizon = 90). ghi : numeric - Global horizontal irradiance. :math:`W/m^2` + Global horizontal irradiance. [Wm⁻²] albedo : numeric, default 0.25 Ground reflectance, typically 0.1-0.4 for surfaces on Earth @@ -546,7 +546,7 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None): Returns ------- grounddiffuse : numeric - Ground reflected irradiance. :math:`W/m^2` + Ground reflected irradiance. [Wm⁻²] Notes ----- @@ -602,7 +602,7 @@ def isotropic(surface_tilt, dhi): (e.g. surface facing up = 0, surface facing horizon = 90) dhi : numeric - Diffuse horizontal irradiance in W/m^2. DHI must be >=0. + Diffuse horizontal irradiance. [Wm⁻²] DHI must be >=0. Returns ------- @@ -663,10 +663,10 @@ def klucher(surface_tilt, surface_azimuth, dhi, ghi, solar_zenith, east of north (e.g. North = 0, South=180 East = 90, West = 270). dhi : numeric - Diffuse horizontal irradiance in W/m^2. DHI must be >=0. + Diffuse horizontal irradiance. [Wm⁻²] DHI must be >=0. ghi : numeric - Global irradiance in W/m^2. DNI must be >=0. + Global irradiance. [Wm⁻²] DNI must be >=0. solar_zenith : numeric Apparent (refraction-corrected) zenith angles in decimal @@ -720,13 +720,10 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra, solar_zenith=None, solar_azimuth=None, projection_ratio=None, return_components=False): r''' - Determine diffuse irradiance from the sky on a tilted surface using - Hay & Davies' 1980 model - - .. math:: - I_{d} = DHI ( A R_b + (1 - A) (\frac{1 + \cos\beta}{2}) ) + Determine diffuse irradiance from the sky on a tilted surface using the + Hay and Davies (1980) model [1]_ [2]_. - Hay and Davies' 1980 model determines the diffuse irradiance from + The Hay and Davies model determines the diffuse irradiance from the sky (ground reflected irradiance is not included in this algorithm) on a tilted surface using the surface tilt angle, surface azimuth angle, diffuse horizontal irradiance, direct normal @@ -746,13 +743,13 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra, South=180, East=90, West=270). dhi : numeric - Diffuse horizontal irradiance in W/m^2. + Diffuse horizontal irradiance. [Wm⁻²] dni : numeric - Direct normal irradiance in W/m^2. + Direct normal irradiance. [Wm⁻²] dni_extra : numeric - Extraterrestrial normal irradiance in W/m^2. + Extraterrestrial normal irradiance. [Wm⁻²] solar_zenith : numeric, optional Solar apparent (refraction-corrected) zenith angles in decimal @@ -769,16 +766,16 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra, projection. Must supply ``solar_zenith`` and ``solar_azimuth`` or supply ``projection_ratio``. - return_components : bool, default False - Flag used to decide whether to return the calculated diffuse components - or not. + return_components : bool, default `False` + If `False`, ``sky_diffuse`` is returned. + If `True`, ``diffuse_components`` is returned. Returns -------- numeric, OrderedDict, or DataFrame - Return type controlled by `return_components` argument. - If ``return_components=False``, `sky_diffuse` is returned. - If ``return_components=True``, `diffuse_components` is returned. + Return type controlled by ``return_components`` argument. + If `False`, ``sky_diffuse`` is returned. + If `True`, ``diffuse_components`` is returned. sky_diffuse : numeric The sky diffuse component of the solar radiation on a tilted @@ -793,20 +790,36 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra, Notes ------ - When supplying ``projection_ratio``, consider constraining its values - when zenith angle approaches 90 degrees or angle of incidence - projection is negative. See code for details. + In the Hay and Davies (1980) model, sky diffuse irradiance, :math:`I_d`, + is as follows: + + .. math:: + I_{d} = DHI \left( A\cdot R_b + (1 - A) \left(\frac{ + 1 + \cos\beta}{2}\right ) \right ). + + :math:`DHI` is the diffuse horizontal irradiance, + :math:`A` is the anisotropy index, which is the ratio of the direct normal + irradiance to the extraterrestrial irradiation, + :math:`R_b` is the projection ratio, which is defined as the ratio of the + cosine of the angle of incidence (AOI) to the cosine of the zenith angle, + and finally :math:`\beta` is the tilt angle of the array. + + If supplying ``projection_ratio``, consider constraining its values + when the zenith angle approaches 90 degrees or the AOI projection is + negative. See code for details. References ----------- - .. [1] Loutzenhiser P.G. et. al. "Empirical validation of models to - compute solar irradiance on inclined surfaces for building energy - simulation" 2007, Solar Energy vol. 81. pp. 254-267 - - .. [2] Hay, J.E., Davies, J.A., 1980. Calculations of the solar + .. [1] Hay, J. E., Davies, J. A., 1980. Calculations of the solar radiation incident on an inclined surface. In: Hay, J.E., Won, T.K. (Eds.), Proc. of First Canadian Solar Radiation Data Workshop, 59. - Ministry of Supply and Services, Canada. + Ministry of Supply and Services, Canada. Available from: + https://archive.org/details/proceedingsfirst00cana/mode/2up + (Last accessed: 17/09/24) + .. [2] Loutzenhiser P. G. et al. "Empirical validation of models to + compute solar irradiance on inclined surfaces for building energy + simulation" 2007, Solar Energy vol. 81. pp. 254-267 + :doi:`10.1016/j.solener.2006.03.009` ''' # if necessary, calculate ratio of titled and horizontal beam irradiance @@ -878,16 +891,16 @@ def reindl(surface_tilt, surface_azimuth, dhi, dni, ghi, dni_extra, South=180 East = 90, West = 270). dhi : numeric - diffuse horizontal irradiance in W/m^2. + diffuse horizontal irradiance. [Wm⁻²] dni : numeric - direct normal irradiance in W/m^2. + direct normal irradiance. [Wm⁻²] ghi: numeric - Global irradiance in W/m^2. + Global irradiance. [Wm⁻²] dni_extra : numeric - Extraterrestrial normal irradiance in W/m^2. + Extraterrestrial normal irradiance. [Wm⁻²] solar_zenith : numeric Apparent (refraction-corrected) zenith angles in decimal degrees. @@ -972,10 +985,10 @@ def king(surface_tilt, dhi, ghi, solar_zenith): surface facing horizon = 90) dhi : numeric - Diffuse horizontal irradiance in W/m^2. + Diffuse horizontal irradiance. [Wm⁻²] ghi : numeric - Global horizontal irradiance in W/m^2. + Global horizontal irradiance. [Wm⁻²] solar_zenith : numeric Apparent (refraction-corrected) zenith angles in decimal degrees. @@ -1029,13 +1042,13 @@ def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra, east of north (e.g. North = 0, South=180 East = 90, West = 270). dhi : numeric - Diffuse horizontal irradiance in W/m^2. DHI must be >=0. + Diffuse horizontal irradiance. [Wm⁻²] DHI must be >=0. dni : numeric - Direct normal irradiance in W/m^2. DNI must be >=0. + Direct normal irradiance. [Wm⁻²] DNI must be >=0. dni_extra : numeric - Extraterrestrial normal irradiance in W/m^2. + Extraterrestrial normal irradiance. [Wm⁻²] solar_zenith : numeric apparent (refraction-corrected) zenith angles in decimal @@ -1255,8 +1268,8 @@ def _f(i, j, zeta): [+0.328, +0.471, -0.216, +0.069, -0.105, -0.028], [+0.557, +0.241, -0.300, +0.086, -0.085, -0.012], [+0.861, -0.323, -0.355, +0.240, -0.467, -0.008], - [ 1.212, -1.239, -0.444, +0.305, -0.797, +0.047], - [ 1.099, -1.847, -0.365, +0.275, -1.132, +0.124], + [+1.212, -1.239, -0.444, +0.305, -0.797, +0.047], + [+1.099, -1.847, -0.365, +0.275, -1.132, +0.124], [+0.544, +0.157, -0.213, +0.118, -1.455, +0.292], [+0.544, +0.157, -0.213, +0.118, -1.455, +0.292], [+0.000, +0.000, +0.000, +0.000, +0.000, +0.000], @@ -1295,13 +1308,13 @@ def perez_driesse(surface_tilt, surface_azimuth, dhi, dni, dni_extra, east of north (e.g. North = 0, South=180 East = 90, West = 270). dhi : numeric - Diffuse horizontal irradiance in W/m^2. dhi must be >=0. + Diffuse horizontal irradiance. [Wm⁻²] dhi must be >=0. dni : numeric - Direct normal irradiance in W/m^2. dni must be >=0. + Direct normal irradiance. [Wm⁻²] dni must be >=0. dni_extra : numeric - Extraterrestrial normal irradiance in W/m^2. + Extraterrestrial normal irradiance. [Wm⁻²] solar_zenith : numeric apparent (refraction-corrected) zenith angles in decimal @@ -1516,16 +1529,16 @@ def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth, solar_azimuth : numeric Solar azimuth angle. [degree] poa_global : numeric - Plane-of-array global irradiance, aka global tilted irradiance. [W/m^2] + Plane-of-array global irradiance, aka global tilted irradiance. [Wm⁻²] dni_extra : numeric, optional - Extraterrestrial direct normal irradiance. [W/m^2] + Extraterrestrial direct normal irradiance. [Wm⁻²] airmass : numeric, optional Relative airmass (not adjusted for pressure). [unitless] albedo : numeric, default 0.25 Ground surface albedo. [unitless] xtol : numeric, default 0.01 Convergence criterion. The estimated GHI will be within xtol of the - true value. Must be positive. [W/m^2] + true value. Must be positive. [Wm⁻²] full_output : boolean, default False If full_output is False, only ghi is returned, otherwise the return value is (ghi, converged, niter). (see Returns section for details). @@ -1533,7 +1546,7 @@ def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth, Returns ------- ghi : numeric - Estimated GHI. [W/m^2] + Estimated GHI. [Wm⁻²] converged : boolean, optional Present if full_output=True. Indicates which elements converged successfully. @@ -1592,7 +1605,7 @@ def clearsky_index(ghi, clearsky_ghi, max_clearsky_index=2.0): Parameters ---------- ghi : numeric - Global horizontal irradiance in W/m^2. + Global horizontal irradiance. [Wm⁻²] clearsky_ghi : numeric Modeled clearsky GHI @@ -1635,7 +1648,7 @@ def clearness_index(ghi, solar_zenith, extra_radiation, min_cos_zenith=0.065, Parameters ---------- ghi : numeric - Global horizontal irradiance in W/m^2. + Global horizontal irradiance. [Wm⁻²] solar_zenith : numeric True (not refraction-corrected) solar zenith angle in decimal @@ -1748,7 +1761,7 @@ def disc(ghi, solar_zenith, datetime_or_doy, pressure=101325, Parameters ---------- ghi : numeric - Global horizontal irradiance in W/m^2. + Global horizontal irradiance. [Wm⁻²] solar_zenith : numeric True (not refraction-corrected) solar zenith angles in decimal @@ -1781,7 +1794,7 @@ def disc(ghi, solar_zenith, datetime_or_doy, pressure=101325, Contains the following keys: * ``dni``: The modeled direct normal irradiance - in W/m^2 provided by the + in Wm⁻² provided by the Direct Insolation Simulation Code (DISC) model. * ``kt``: Ratio of global to extraterrestrial irradiance on a horizontal plane. @@ -1894,7 +1907,7 @@ def dirint(ghi, solar_zenith, times, pressure=101325., use_delta_kt_prime=True, Parameters ---------- ghi : array-like - Global horizontal irradiance in W/m^2. + Global horizontal irradiance. [Wm⁻²] solar_zenith : array-like True (not refraction-corrected) solar_zenith angles in decimal @@ -1932,7 +1945,7 @@ def dirint(ghi, solar_zenith, times, pressure=101325., use_delta_kt_prime=True, Returns ------- dni : array-like - The modeled direct normal irradiance in W/m^2 provided by the + The modeled direct normal irradiance in Wm⁻² provided by the DIRINT model. Notes @@ -2136,13 +2149,13 @@ def dirindex(ghi, ghi_clearsky, dni_clearsky, zenith, times, pressure=101325., Parameters ---------- ghi : array-like - Global horizontal irradiance in W/m^2. + Global horizontal irradiance. [Wm⁻²] ghi_clearsky : array-like - Global horizontal irradiance from clear sky model, in W/m^2. + Global horizontal irradiance from clear sky model. [Wm⁻²] dni_clearsky : array-like - Direct normal irradiance from clear sky model, in W/m^2. + Direct normal irradiance from clear sky model. [Wm⁻²] zenith : array-like True (not refraction-corrected) zenith angles in decimal @@ -2181,7 +2194,7 @@ def dirindex(ghi, ghi_clearsky, dni_clearsky, zenith, times, pressure=101325., Returns ------- dni : array-like - The modeled direct normal irradiance in W/m^2. + The modeled direct normal irradiance. [Wm⁻²] Notes ----- @@ -2228,12 +2241,12 @@ def gti_dirint(poa_global, aoi, solar_zenith, solar_azimuth, times, Model performance is poor for AOI greater than approximately 80 degrees `and` plane of array irradiance greater than - approximately 200 W/m^2. + approximately 200 Wm⁻². Parameters ---------- poa_global : array-like - Plane of array global irradiance in W/m^2. + Plane of array global irradiance. [Wm⁻²] aoi : array-like Angle of incidence of solar rays with respect to the module @@ -2300,10 +2313,10 @@ def gti_dirint(poa_global, aoi, solar_zenith, solar_azimuth, times, data : DataFrame Contains the following keys/columns: - * ``ghi``: the modeled global horizontal irradiance in W/m^2. - * ``dni``: the modeled direct normal irradiance in W/m^2. + * ``ghi``: the modeled global horizontal irradiance. [Wm⁻²] + * ``dni``: the modeled direct normal irradiance. [Wm⁻²] * ``dhi``: the modeled diffuse horizontal irradiance in - W/m^2. + Wm⁻². References ---------- @@ -2384,7 +2397,7 @@ def _gti_dirint_lt_90(poa_global, aoi, aoi_lt_90, solar_zenith, solar_azimuth, for iteration, coeff in enumerate(coeffs): # test if difference between modeled GTI and - # measured GTI (poa_global) is less than 1 W/m^2 + # measured GTI (poa_global) is less than 1 Wm⁻² # only test for aoi less than 90 deg best_diff_lte_1 = best_diff <= 1 best_diff_lte_1_lt_90 = best_diff_lte_1[aoi_lt_90] @@ -2565,7 +2578,7 @@ def erbs(ghi, zenith, datetime_or_doy, min_cos_zenith=0.065, max_zenith=87): Parameters ---------- ghi: numeric - Global horizontal irradiance in W/m^2. + Global horizontal irradiance. [Wm⁻²] zenith: numeric True (not refraction-corrected) zenith angles in decimal degrees. datetime_or_doy : int, float, array, pd.DatetimeIndex @@ -2583,9 +2596,9 @@ def erbs(ghi, zenith, datetime_or_doy, min_cos_zenith=0.065, max_zenith=87): data : OrderedDict or DataFrame Contains the following keys/columns: - * ``dni``: the modeled direct normal irradiance in W/m^2. + * ``dni``: the modeled direct normal irradiance. [Wm⁻²] * ``dhi``: the modeled diffuse horizontal irradiance in - W/m^2. + Wm⁻². * ``kt``: Ratio of global to extraterrestrial irradiance on a horizontal plane. @@ -2663,7 +2676,7 @@ def erbs_driesse(ghi, zenith, datetime_or_doy=None, dni_extra=None, Parameters ---------- ghi: numeric - Global horizontal irradiance in W/m^2. + Global horizontal irradiance. [Wm⁻²] zenith: numeric True (not refraction-corrected) zenith angles in decimal degrees. datetime_or_doy : int, float, array or pd.DatetimeIndex, optional @@ -2686,9 +2699,9 @@ def erbs_driesse(ghi, zenith, datetime_or_doy=None, dni_extra=None, data : OrderedDict or DataFrame Contains the following keys/columns: - * ``dni``: the modeled direct normal irradiance in W/m^2. + * ``dni``: the modeled direct normal irradiance. [Wm⁻²] * ``dhi``: the modeled diffuse horizontal irradiance in - W/m^2. + Wm⁻². * ``kt``: Ratio of global to extraterrestrial irradiance on a horizontal plane. @@ -2784,7 +2797,7 @@ def orgill_hollands(ghi, zenith, datetime_or_doy, dni_extra=None, Parameters ---------- ghi: numeric - Global horizontal irradiance in W/m^2. + Global horizontal irradiance. [Wm⁻²] zenith: numeric True (not refraction-corrected) zenith angles in decimal degrees. datetime_or_doy : int, float, array, pd.DatetimeIndex @@ -2804,9 +2817,9 @@ def orgill_hollands(ghi, zenith, datetime_or_doy, dni_extra=None, data : OrderedDict or DataFrame Contains the following keys/columns: - * ``dni``: the modeled direct normal irradiance in W/m^2. + * ``dni``: the modeled direct normal irradiance. [Wm⁻²] * ``dhi``: the modeled diffuse horizontal irradiance in - W/m^2. + Wm⁻². * ``kt``: Ratio of global to extraterrestrial irradiance on a horizontal plane. @@ -2877,7 +2890,7 @@ def boland(ghi, solar_zenith, datetime_or_doy, a_coeff=8.645, b_coeff=0.613, Parameters ---------- ghi: numeric - Global horizontal irradiance. [W/m^2] + Global horizontal irradiance. [Wm⁻²] solar_zenith: numeric True (not refraction-corrected) zenith angles in decimal degrees. datetime_or_doy : numeric, pandas.DatetimeIndex @@ -2899,9 +2912,9 @@ def boland(ghi, solar_zenith, datetime_or_doy, a_coeff=8.645, b_coeff=0.613, data : OrderedDict or DataFrame Contains the following keys/columns: - * ``dni``: the modeled direct normal irradiance in W/m^2. + * ``dni``: the modeled direct normal irradiance. [Wm⁻²] * ``dhi``: the modeled diffuse horizontal irradiance in - W/m^2. + Wm⁻². * ``kt``: Ratio of global to extraterrestrial irradiance on a horizontal plane. @@ -2990,7 +3003,7 @@ def campbell_norman(zenith, transmittance, pressure=101325.0, ------- irradiance: DataFrame Modeled direct normal irradiance, direct horizontal irradiance, - and global horizontal irradiance in W/m^2 + and global horizontal irradiance in Wm⁻² References ---------- @@ -3047,7 +3060,7 @@ def _liujordan(zenith, transmittance, airmass, dni_extra=1367.0): ------- irradiance: DataFrame Modeled direct normal irradiance, direct horizontal irradiance, - and global horizontal irradiance in W/m^2 + and global horizontal irradiance in Wm⁻² References ---------- @@ -3721,7 +3734,7 @@ def louche(ghi, solar_zenith, datetime_or_doy, max_zenith=90): Parameters ---------- ghi : numeric - Global horizontal irradiance. [W/m^2] + Global horizontal irradiance. [Wm⁻²] solar_zenith : numeric True (not refraction-corrected) zenith angles in decimal @@ -3736,9 +3749,9 @@ def louche(ghi, solar_zenith, datetime_or_doy, max_zenith=90): data: OrderedDict or DataFrame Contains the following keys/columns: - * ``dni``: the modeled direct normal irradiance in W/m^2. + * ``dni``: the modeled direct normal irradiance. [Wm⁻²] * ``dhi``: the modeled diffuse horizontal irradiance in - W/m^2. + Wm⁻². * ``kt``: Ratio of global to extraterrestrial irradiance on a horizontal plane.