From 94c3fc5912bdc9f67655f5b71d17211ee2c85384 Mon Sep 17 00:00:00 2001 From: RDaxini <143435106+RDaxini@users.noreply.github.com> Date: Thu, 26 Sep 2024 16:45:36 +0100 Subject: [PATCH] Update irradiance.klucher docs (#2192) * Update irradiance.py move eqn and add description and variables definition to a new notes section update references redefine surface tilt for consistency with #2191 * Update irradiance.py update variable names (I_d0 to DHI and add definition of theta as aoi) * Update irradiance.py add doi * Update irradiance.py wording in definition of F' * Update irradiance.py * Update irradiance.py \theta->\beta reinstate Loutzenhiser reference * Update irradiance.py add doi to * Update irradiance.py * Update irradiance.py add units to returns statement * typo * Update v0.11.1.rst * Update v0.11.1.rst * update model description * whatsnew, update and merge entries * whatsnew (missing word) * move references (klucher and haydavies) moved references from first line to notes section --- docs/sphinx/source/whatsnew/v0.11.1.rst | 7 ++- pvlib/irradiance.py | 78 ++++++++++++++----------- 2 files changed, 47 insertions(+), 38 deletions(-) diff --git a/docs/sphinx/source/whatsnew/v0.11.1.rst b/docs/sphinx/source/whatsnew/v0.11.1.rst index 8757d77617..f4a7a4a9de 100644 --- a/docs/sphinx/source/whatsnew/v0.11.1.rst +++ b/docs/sphinx/source/whatsnew/v0.11.1.rst @@ -75,9 +75,10 @@ Documentation * 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`) - +* Updated model description, added equation variable definitions, and created a + new "notes" section in :py:func:`pvlib.irradiance.haydavies` and + :py:func:`pvlib.irradiance.klucher` (:issue:`2183`, :pull:`2191`, + :pull:`2192`) * Split the contributing page into several pages (:issue:`2210`, :pull:`2219`) Requirements diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index 77f9ead91f..db62439772 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -630,66 +630,74 @@ def klucher(surface_tilt, surface_azimuth, dhi, ghi, solar_zenith, solar_azimuth): r''' Determine diffuse irradiance from the sky on a tilted surface - using Klucher's 1979 model - - .. math:: - - I_{d} = DHI \frac{1 + \cos\beta}{2} (1 + F' \sin^3(\beta/2)) - (1 + F' \cos^2\theta\sin^3\theta_z) - - where - - .. math:: - - F' = 1 - (I_{d0} / GHI)^2 - - Klucher's 1979 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 irradiance, global - horizontal irradiance, extraterrestrial irradiance, sun zenith - angle, and sun azimuth angle. + using the Klucher (1979) model. Parameters ---------- surface_tilt : numeric - Surface tilt angles in decimal degrees. surface_tilt must be >=0 + Surface tilt angles in decimal degrees. ``surface_tilt`` must be >=0 and <=180. The tilt angle is defined as degrees from horizontal (e.g. surface facing up = 0, surface facing horizon = 90) surface_azimuth : numeric - Surface azimuth angles in decimal degrees. surface_azimuth must + Surface azimuth angles in decimal degrees. ``surface_azimuth`` must be >=0 and <=360. The Azimuth convention is defined as degrees east of north (e.g. North = 0, South=180 East = 90, West = 270). dhi : numeric - Diffuse horizontal irradiance. [Wm⁻²] DHI must be >=0. + Diffuse horizontal irradiance, must be >=0. [Wm⁻²] ghi : numeric - Global irradiance. [Wm⁻²] DNI must be >=0. + Global horizontal irradiance, must be >=0. [Wm⁻²] solar_zenith : numeric Apparent (refraction-corrected) zenith angles in decimal - degrees. solar_zenith must be >=0 and <=180. + degrees. ``solar_zenith`` must be >=0 and <=180. solar_azimuth : numeric - Sun azimuth angles in decimal degrees. solar_azimuth must be >=0 + Sun azimuth angles in decimal degrees. ``solar_azimuth`` must be >=0 and <=360. The Azimuth convention is defined as degrees east of north (e.g. North = 0, East = 90, West = 270). Returns ------- diffuse : numeric - The sky diffuse component of the solar radiation. + The sky diffuse component of the solar radiation. [Wm⁻²] + + Notes + ----- + The Klucher (1979) model [1]_ [2]_ 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, global horizontal irradiance, + sun zenith angle, and sun azimuth angle. The expression for the sky diffuse + irradiance, :math:`I_d`, is as follows: + + .. math:: + + I_{d} = DHI \frac{1 + \cos\beta}{2} (1 + F' \sin^3(\beta/2)) + (1 + F' \cos^2\theta\sin^3\theta_z). + + DHI is the diffuse horizontal irradiance, :math:`\beta` is the surface + tilt angle, :math:`\theta_z` is the solar zenith angle, and :math:`\theta` + is the angle of incidence. :math:`F'` is a modulating function to account + for when the sky changes from clear to overcast, and is defined as follows: + + .. math:: + + F' = 1 - (DHI / GHI)^2, + + where GHI is the global horiztonal irradiance. 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] Klucher, T.M., 1979. Evaluation of models to predict insolation on - tilted surfaces. Solar Energy 23 (2), 111-114. + .. [1] Klucher, T. M. "Evaluation of models to predict insolation on + tilted surfaces" 1979, Solar Energy vol. 23 (2), pp. 111-114 + :doi:`10.1016/0038-092X(79)90110-5` + .. [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` ''' # zenith angle with respect to panel normal. @@ -721,7 +729,7 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra, return_components=False): r''' Determine diffuse irradiance from the sky on a tilted surface using the - Hay and Davies (1980) model [1]_ [2]_. + Hay and Davies (1980) model. The Hay and Davies model determines the diffuse irradiance from the sky (ground reflected irradiance is not included in this @@ -790,8 +798,8 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra, Notes ------ - In the Hay and Davies (1980) model, sky diffuse irradiance, :math:`I_d`, - is as follows: + In the Hay and Davies (1980) model [1]_ [2]_, sky diffuse irradiance, + :math:`I_d`, is as follows: .. math:: I_{d} = DHI \left( A\cdot R_b + (1 - A) \left(\frac{