Improve docstring for get_ground_diffuse (#1953)

* improve docstring for get_ground_diffuse

* fix formatting. Reduce description text. Whatsnew

* try to get the sphinx reference

* sphinx reference

* use doi

* use math

* use math

* r

* Update pvlib/irradiance.py

Co-authored-by: Kevin Anderson <[email protected]>

---------

Co-authored-by: Kevin Anderson <[email protected]>

Author: cwhanse

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
 ~~~~~~~~~~~~
 

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`
     '''