diff --git a/docs/sphinx/source/whatsnew/v0.10.4.rst b/docs/sphinx/source/whatsnew/v0.10.4.rst index 997ca4c249..ad8573383d 100644 --- a/docs/sphinx/source/whatsnew/v0.10.4.rst +++ b/docs/sphinx/source/whatsnew/v0.10.4.rst @@ -34,9 +34,11 @@ Testing Documentation ~~~~~~~~~~~~~ +* Improved references and description for :py:func:`~pvlib.irradiance.get_ground_diffuse`. (:pull:`1953`) * Fixed broken URLs in various places. (:pull:`1957`, :pull:`1960`) * Clarified documentation for :py:func:`~pvlib.irradiance.get_ground_diffuse`. (:pull:`1883`) + Requirements ~~~~~~~~~~~~ diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index 38b683585c..dd2b32371f 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -551,15 +551,16 @@ def poa_components(aoi, dni, poa_sky_diffuse, poa_ground_diffuse): def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None): - ''' - Estimate diffuse irradiance from ground reflections given - irradiance, albedo, and surface tilt. The ground is assumed to - be horizontal, flat and Lambertian, and the reflected irradiance - is isotropic. + r''' + Estimate diffuse irradiance on a tilted surface from ground reflections. + + Ground diffuse irradiance is calculated as + + .. math:: + + G_{ground} = GHI \times \rho \times \frac{1 - \cos\beta}{2} - Function to determine the portion of irradiance on a tilted surface - due to ground reflections. Any of the inputs may be DataFrames or - scalars. + where :math:`\rho` is ``albedo`` and :math:`\beta` is ``surface_tilt``. Parameters ---------- @@ -569,13 +570,13 @@ 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. [W/m^2] + Global horizontal irradiance. :math:`W/m^2` albedo : numeric, default 0.25 Ground reflectance, typically 0.1-0.4 for surfaces on Earth (land), may increase over snow, ice, etc. May also be known as the reflection coefficient. Must be >=0 and <=1. Will be - overridden if surface_type is supplied. + overridden if ``surface_type`` is supplied. surface_type : string, optional If supplied, overrides ``albedo``. ``surface_type`` can be one of @@ -586,22 +587,22 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None): Returns ------- grounddiffuse : numeric - Ground reflected irradiance. [W/m^2] + Ground reflected irradiance. :math:`W/m^2` + Notes + ----- + Table of albedo values by ``surface_type`` are from [2]_, [3]_, [4]_; + see :py:data:`~pvlib.irradiance.SURFACE_ALBEDOS`. 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. - - The calculation is the last term of equations 3, 4, 7, 8, 10, 11, and 12. - - .. [2] albedos from: - http://files.pvsyst.com/help/albedo.htm - and - http://en.wikipedia.org/wiki/Albedo - and + .. [2] https://www.pvsyst.com/help/albedo.htm Accessed January, 2024. + .. [3] http://en.wikipedia.org/wiki/Albedo Accessed January, 2024. + .. [4] Payne, R. E. "Albedo of the Sea Surface". J. Atmos. Sci., 29, + pp. 959–970, 1972. :doi:`10.1175/1520-0469(1972)029<0959:AOTSS>2.0.CO;2` '''