Standardize diffuse irradiance component names and descriptions in docstrings (#2827)

* Standardize component names and descriptions

* Add whatsnew entry

* Fix list indentation

* Edit nomenclature

Author: cbcrespo

docs/sphinx/source/user_guide/extras/nomenclature.rst

@@ -134,23 +134,33 @@ There is a convention on consistent variable names throughout the library:
 
     photocurrent
         Photocurrent
+		
+	poa_circumsolar
+		The portion of sky diffuse irradiance on a tilted plane from the circumsolar
+		region. [Wm⁻²]
 
     poa_diffuse
-        Total diffuse irradiance in plane [Wm⁻²]. Sum of ground and sky diffuse
+        Total diffuse irradiance on a tilted plane [Wm⁻²]. Sum of ground and sky diffuse
         components of global irradiance.
 
     poa_direct
-        Direct/beam irradiance in plane [Wm⁻²].
+        Direct irradiance on a tilted plane [Wm⁻²].
 
     poa_global
-        Global irradiance in plane.  Sum of diffuse and beam projection [Wm⁻²].
+        Total irradiance on a tilted plane. [Wm⁻²]
 
     poa_ground_diffuse
-        In plane ground reflected irradiance [Wm⁻²].
+        The ground diffuse component of irradiance on a tilted plane. [Wm⁻²]
+
+	poa_horizon
+		The portion of sky diffuse irradiance on a tilted plane from the horizon. [Wm⁻²]
+
+	poa_isotropic
+		The portion of sky diffuse irradiance on a tilted plane from the isotropic
+		sky dome. [Wm⁻²]
 
     poa_sky_diffuse
-        Diffuse irradiance in plane from scattered light in the atmosphere
-        (without ground reflected irradiance) [Wm⁻²].
+        The sky diffuse component of irradiance on a tilted plane. [Wm⁻²]
 
     precipitable_water
         Total precipitable water contained in a column of unit cross section

docs/sphinx/source/whatsnew/v0.15.3.rst

@@ -39,6 +39,8 @@ Documentation
 * Fix broken link in GitHub Contributing tab. (:issue:`2628`, :pull:`2806`)
 * Fixed broken ``interval`` keyword argument in the ``oedi_9068`` gallery
   example; the correct parameter name is ``time_step``. (:issue:`2791`)
+* Standardized diffuse component names and descriptions in the docstrings of
+  multiple functions in :py:mod:`pvlib.irradiance`. (:pull:`2827`)
 
 
 Testing

pvlib/irradiance.py

@@ -566,8 +566,8 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None):
 
     Returns
     -------
-    grounddiffuse : numeric
-        Ground reflected irradiance. [Wm⁻²]
+    poa_ground_diffuse : numeric
+        The ground diffuse component of irradiance on a tilted plane. [Wm⁻²]
 
     Notes
     -----
@@ -589,14 +589,17 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None):
     if surface_type is not None:
         albedo = pvlib.albedo.SURFACE_ALBEDOS[surface_type]
 
-    diffuse_irrad = ghi * albedo * (1 - np.cos(np.radians(surface_tilt))) * 0.5
+    poa_ground_diffuse = (
+        ghi * albedo *
+        (1 - np.cos(np.radians(surface_tilt))) * 0.5
+    )
 
     try:
-        diffuse_irrad.name = 'diffuse_ground'
+        poa_ground_diffuse.name = 'poa_ground_diffuse'
     except AttributeError:
         pass
 
-    return diffuse_irrad
+    return poa_ground_diffuse
 
 
 def isotropic(surface_tilt, dhi):
@@ -673,8 +676,8 @@ def klucher(surface_tilt, surface_azimuth, dhi, ghi, solar_zenith,
 
     Returns
     -------
-    diffuse : numeric
-        The sky diffuse component of the solar radiation. [Wm⁻²]
+    poa_sky_diffuse : numeric
+        The sky diffuse component of irradiance on a tilted plane. [Wm⁻²]
 
     Notes
     -----
@@ -699,7 +702,7 @@ def klucher(surface_tilt, surface_azimuth, dhi, ghi, solar_zenith,
 
        F' = 1 - (DHI / GHI)^2,
 
-    where GHI is the global horiztonal irradiance.
+    where GHI is the global horizontal irradiance.
 
     References
     ----------
@@ -731,9 +734,9 @@ def klucher(surface_tilt, surface_azimuth, dhi, ghi, solar_zenith,
     term2 = 1 + F * (tools.sind(0.5 * surface_tilt) ** 3)
     term3 = 1 + F * (cos_tt ** 2) * (tools.sind(solar_zenith) ** 3)
 
-    sky_diffuse = dhi * term1 * term2 * term3
+    poa_sky_diffuse = dhi * term1 * term2 * term3
 
-    return sky_diffuse
+    return poa_sky_diffuse
 
 
 def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
@@ -782,25 +785,28 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
         or supply ``projection_ratio``.
 
     return_components : bool, default `False`
-        If `False`, ``sky_diffuse`` is returned.
+        If `False`, ``poa_sky_diffuse`` is returned.
         If `True`, ``diffuse_components`` is returned.
 
     Returns
     --------
     numeric, dict, or DataFrame
         Return type controlled by ``return_components`` argument.
-        If `False`, ``sky_diffuse`` is returned.
+        If `False`, ``poa_sky_diffuse`` is returned.
         If `True`, ``diffuse_components`` is returned.
 
-    sky_diffuse : numeric
-        The sky diffuse component of the solar radiation on a tilted
-        surface. [Wm⁻²]
+    poa_sky_diffuse : numeric
+        The sky diffuse component of irradiance on a tilted plane. [Wm⁻²]
 
     diffuse_components : dict (array input) or DataFrame (Series input)
         Keys/columns are:
-            * poa_sky_diffuse: Total sky diffuse
-            * poa_isotropic
-            * poa_circumsolar
+            * poa_sky_diffuse: The sky diffuse component of irradiance on a
+              tilted plane. [Wm⁻²]
+            * poa_isotropic: The portion of sky diffuse irradiance on a tilted
+              plane from the isotropic sky dome. [Wm⁻²]
+            * poa_circumsolar: The portion of sky diffuse irradiance on a
+              tilted plane from the circumsolar region. [Wm⁻²]
+
 
     Notes
     ------
@@ -855,20 +861,20 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     poa_isotropic = np.maximum(dhi * term1 * term2, 0)
     poa_circumsolar = np.maximum(dhi * (AI * Rb), 0)
-    sky_diffuse = poa_isotropic + poa_circumsolar
+    poa_sky_diffuse = poa_isotropic + poa_circumsolar
 
     if return_components:
         diffuse_components = {
-            'poa_sky_diffuse': sky_diffuse,
+            'poa_sky_diffuse': poa_sky_diffuse,
             'poa_isotropic': poa_isotropic,
             'poa_circumsolar': poa_circumsolar
         }
 
-        if isinstance(sky_diffuse, pd.Series):
+        if isinstance(poa_sky_diffuse, pd.Series):
             diffuse_components = pd.DataFrame(diffuse_components)
         return diffuse_components
     else:
-        return sky_diffuse
+        return poa_sky_diffuse
 
 
 def reindl(surface_tilt, surface_azimuth, dhi, dni, ghi, dni_extra,
@@ -1055,15 +1061,17 @@ def king(surface_tilt, dhi, ghi, solar_zenith):
     Returns
     --------
     poa_sky_diffuse : numeric
-        The diffuse component of the solar radiation.
+        The sky diffuse component of irradiance on a tilted plane. [Wm⁻²]
     '''
 
-    sky_diffuse = (dhi * (1 + tools.cosd(surface_tilt)) / 2 + ghi *
-                   (0.012 * solar_zenith - 0.04) *
-                   (1 - tools.cosd(surface_tilt)) / 2)
-    sky_diffuse = np.maximum(sky_diffuse, 0)
+    poa_sky_diffuse = (
+        dhi * (1 + tools.cosd(surface_tilt)) / 2 + ghi *
+        (0.012 * solar_zenith - 0.04) *
+        (1 - tools.cosd(surface_tilt)) / 2
+    )
+    poa_sky_diffuse = np.maximum(poa_sky_diffuse, 0)
 
-    return sky_diffuse
+    return poa_sky_diffuse
 
 
 def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
@@ -1103,7 +1111,6 @@ def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
     dni : numeric
         Direct normal irradiance, must be >=0. [Wm⁻²]
 
-
     dni_extra : numeric
         Extraterrestrial normal irradiance. [Wm⁻²]
 
@@ -1145,19 +1152,23 @@ def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
     --------
     numeric, dict, or DataFrame
         Return type controlled by `return_components` argument.
-        If ``return_components=False``, `sky_diffuse` is returned.
+        If ``return_components=False``, `poa_sky_diffuse` is returned.
         If ``return_components=True``, `diffuse_components` is returned.
 
-    sky_diffuse : numeric
+    poa_sky_diffuse : numeric
         The sky diffuse component of the solar radiation on a tilted
-        surface.
+        plane. [Wm⁻²]
 
     diffuse_components : dict (array input) or DataFrame (Series input)
         Keys/columns are:
-            * poa_sky_diffuse: Total sky diffuse
-            * poa_isotropic
-            * poa_circumsolar
-            * poa_horizon
+            * poa_sky_diffuse: The sky diffuse component of irradiance on a
+              tilted plane. [Wm⁻²]
+            * poa_isotropic: The portion of sky diffuse irradiance on a tilted
+              plane from the isotropic sky dome. [Wm⁻²]
+            * poa_circumsolar: The portion of sky diffuse irradiance on a
+              tilted plane from the circumsolar region. [Wm⁻²]
+            * poa_horizon: The portion of sky diffuse irradiance on a tilted
+              plane from the horizon. [Wm⁻²]
 
 
     References
@@ -1230,33 +1241,33 @@ def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
     term2 = F1 * A / B
     term3 = F2 * tools.sind(surface_tilt)
 
-    sky_diffuse = np.maximum(dhi * (term1 + term2 + term3), 0)
+    poa_sky_diffuse = np.maximum(dhi * (term1 + term2 + term3), 0)
 
     # we've preserved the input type until now, so don't ruin it!
-    if isinstance(sky_diffuse, pd.Series):
-        sky_diffuse[np.isnan(airmass)] = 0
+    if isinstance(poa_sky_diffuse, pd.Series):
+        poa_sky_diffuse[np.isnan(airmass)] = 0
     else:
-        sky_diffuse = np.where(np.isnan(airmass), 0, sky_diffuse)
+        poa_sky_diffuse = np.where(np.isnan(airmass), 0, poa_sky_diffuse)
 
     if return_components:
         diffuse_components = {
-            'poa_sky_diffuse': sky_diffuse,
+            'poa_sky_diffuse': poa_sky_diffuse,
             'poa_isotropic': dhi * term1,
             'poa_circumsolar': dhi * term2,
             'poa_horizon': dhi * term3
         }
 
-        # Set values of components to 0 when sky_diffuse is 0
-        mask = sky_diffuse == 0
-        if isinstance(sky_diffuse, pd.Series):
+        # Set values of components to 0 when poa_sky_diffuse is 0
+        mask = poa_sky_diffuse == 0
+        if isinstance(poa_sky_diffuse, pd.Series):
             diffuse_components = pd.DataFrame(diffuse_components)
             diffuse_components.loc[mask] = 0
         else:
             diffuse_components = {k: np.where(mask, 0, v) for k, v in
                                   diffuse_components.items()}
         return diffuse_components
     else:
-        return sky_diffuse
+        return poa_sky_diffuse
 
 
 def _calc_delta(dhi, dni_extra, solar_zenith, airmass=None):
@@ -1362,7 +1373,6 @@ def perez_driesse(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
     dni : numeric
         Direct normal irradiance, must be >=0. [Wm⁻²]
 
-
     dni_extra : numeric
         Extraterrestrial normal irradiance. [Wm⁻²]
 
@@ -1386,19 +1396,22 @@ def perez_driesse(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
     --------
     numeric, dict, or DataFrame
         Return type controlled by `return_components` argument.
-        If ``return_components=False``, `sky_diffuse` is returned.
+        If ``return_components=False``, `poa_sky_diffuse` is returned.
         If ``return_components=True``, `diffuse_components` is returned.
 
-    sky_diffuse : numeric
-        The sky diffuse component of the solar radiation on a tilted
-        surface.
+    poa_sky_diffuse : numeric
+        The sky diffuse component of irradiance on a tilted plane. [Wm⁻²]
 
     diffuse_components : dict (array input) or DataFrame (Series input)
         Keys/columns are:
-            * poa_sky_diffuse: Total sky diffuse
-            * poa_isotropic
-            * poa_circumsolar
-            * poa_horizon
+            * poa_sky_diffuse: The sky diffuse component of irradiance on a
+              tilted plane. [Wm⁻²]
+            * poa_isotropic: The portion of sky diffuse irradiance on a
+              tilted plane from the isotropic sky dome. [Wm⁻²]
+            * poa_circumsolar: The portion of sky diffuse irradiance on a
+              tilted plane from the circumsolar region. [Wm⁻²]
+            * poa_horizon: The portion of sky diffuse irradiance on a tilted
+              plane from the horizon. [Wm⁻²]
 
     Notes
     -----
@@ -1455,22 +1468,22 @@ def perez_driesse(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
     term2 = F1 * A / B
     term3 = F2 * tools.sind(surface_tilt)
 
-    sky_diffuse = np.maximum(dhi * (term1 + term2 + term3), 0)
+    poa_sky_diffuse = np.maximum(dhi * (term1 + term2 + term3), 0)
 
     if return_components:
         diffuse_components = {
-            'poa_sky_diffuse': sky_diffuse,
+            'poa_sky_diffuse': poa_sky_diffuse,
             'poa_isotropic': dhi * term1,
             'poa_circumsolar': dhi * term2,
             'poa_horizon': dhi * term3
         }
 
-        if isinstance(sky_diffuse, pd.Series):
+        if isinstance(poa_sky_diffuse, pd.Series):
             diffuse_components = pd.DataFrame(diffuse_components)
 
         return diffuse_components
     else:
-        return sky_diffuse
+        return poa_sky_diffuse
 
 
 def _poa_from_ghi(surface_tilt, surface_azimuth,

tests/test_irradiance.py

@@ -128,7 +128,7 @@ def test_get_ground_diffuse_simple_float():
 
 def test_get_ground_diffuse_simple_series(irrad_data):
     ground_irrad = irradiance.get_ground_diffuse(40, irrad_data['ghi'])
-    assert ground_irrad.name == 'diffuse_ground'
+    assert ground_irrad.name == 'poa_ground_diffuse'
 
 
 def test_get_ground_diffuse_albedo_0(irrad_data):
@@ -142,7 +142,7 @@ def test_get_ground_diffuse_albedo_series(times):
     ground_irrad = irradiance.get_ground_diffuse(
         45, pd.Series(1000, index=times), albedo)
     expected = albedo * 0.5 * (1 - np.sqrt(2) / 2.) * 1000
-    expected.name = 'diffuse_ground'
+    expected.name = 'poa_ground_diffuse'
     assert_series_equal(ground_irrad, expected)