From d0173e167d38e213e77935c231ec3341d5f81f20 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Fri, 26 Jan 2024 13:11:17 -0700 Subject: [PATCH 1/9] improve docstring for get_ground_diffuse --- pvlib/irradiance.py | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index 174a88e6a0..69c6fabf8f 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -567,13 +567,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 @@ -584,23 +584,25 @@ 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 + ----- + Ground diffuse irradiance is the the last term of equations 3, 4, 7, 8, + 10, 11, and 12 in [1]_. Table of albedo values + (see :p:data::`SURFACE_ALBEDOS`) from [2]_, [3], [4]_. 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 - https://doi.org/10.1175/1520-0469(1972)029<0959:AOTSS>2.0.CO;2 + .. [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. + https://doi.org/10.1175/1520-0469(1972)029<0959:AOTSS>2.0.CO;2. ''' if surface_type is not None: From 5f23a6e465db0335259a91753afb401b011868b4 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Fri, 26 Jan 2024 13:30:53 -0700 Subject: [PATCH 2/9] fix formatting. Reduce description text. Whatsnew --- docs/sphinx/source/whatsnew/v0.10.4.rst | 3 ++- pvlib/irradiance.py | 19 +++++++------------ 2 files changed, 9 insertions(+), 13 deletions(-) diff --git a/docs/sphinx/source/whatsnew/v0.10.4.rst b/docs/sphinx/source/whatsnew/v0.10.4.rst index df73d68e98..b85dc69d55 100644 --- a/docs/sphinx/source/whatsnew/v0.10.4.rst +++ b/docs/sphinx/source/whatsnew/v0.10.4.rst @@ -20,7 +20,7 @@ Testing Documentation ~~~~~~~~~~~~~ - +* Improved references and description for :py:func:`~pvlib.irradiance.get_ground_diffuse`. (:pull:`1953`) Requirements ~~~~~~~~~~~~ @@ -29,3 +29,4 @@ Requirements Contributors ~~~~~~~~~~~~ * :ghuser:`matsuobasho` +* :ghuser:`cwhanse` diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index 69c6fabf8f..890187e21b 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -552,12 +552,7 @@ 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. - - Function to determine the portion of irradiance on a tilted surface - due to ground reflections. Any of the inputs may be DataFrames or - scalars. + Estimate diffuse irradiance on a tilted surface from ground reflections. Parameters ---------- @@ -567,7 +562,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. :math:`W/m^2` albedo : numeric, default 0.25 Ground reflectance, typically 0.1-0.4 for surfaces on Earth @@ -584,22 +579,22 @@ 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. :math:`W/m^2` Notes ----- Ground diffuse irradiance is the the last term of equations 3, 4, 7, 8, - 10, 11, and 12 in [1]_. Table of albedo values - (see :p:data::`SURFACE_ALBEDOS`) from [2]_, [3], [4]_. + 10, 11, and 12 in [1]_. Table of albedo values by ``surface_type`` + in :py:data::`SURFACE_ALBEDOS` from [2]_, [3]_, [4]_. 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] https://www.pvsyst.com/help/albedo.htm, Accessed January, 2024. - .. [3] http://en.wikipedia.org/wiki/Albedo. Accessed January, 2024. + .. [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. https://doi.org/10.1175/1520-0469(1972)029<0959:AOTSS>2.0.CO;2. From 1bd9fb8ee94a5accd7e2f18f2a85f09c9b29666a Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Fri, 26 Jan 2024 13:50:27 -0700 Subject: [PATCH 3/9] try to get the sphinx reference --- pvlib/irradiance.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index 890187e21b..154a58e105 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -581,12 +581,11 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None): grounddiffuse : numeric Ground reflected irradiance. :math:`W/m^2` - Notes ----- Ground diffuse irradiance is the the last term of equations 3, 4, 7, 8, 10, 11, and 12 in [1]_. Table of albedo values by ``surface_type`` - in :py:data::`SURFACE_ALBEDOS` from [2]_, [3]_, [4]_. + are from [2]_, [3]_, [4]_; see :py:data:`SURFACE_ALBEDOS`. References ---------- From ea8342650584d6728ea5f8be6ba3c6fd2ab3e68f Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Fri, 26 Jan 2024 13:59:11 -0700 Subject: [PATCH 4/9] sphinx reference --- pvlib/irradiance.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index 154a58e105..ac0ef73070 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -585,7 +585,8 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None): ----- Ground diffuse irradiance is the the last term of equations 3, 4, 7, 8, 10, 11, and 12 in [1]_. Table of albedo values by ``surface_type`` - are from [2]_, [3]_, [4]_; see :py:data:`SURFACE_ALBEDOS`. + are from [2]_, [3]_, [4]_; + see :py:data:`~pvlib.irradiance.SURFACE_ALBEDOS`. References ---------- From 43c346fceb6bd1c693331ee55da5c03b54797608 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Fri, 26 Jan 2024 16:23:56 -0700 Subject: [PATCH 5/9] use doi --- pvlib/irradiance.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index ac0ef73070..845ed06f2b 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -597,7 +597,7 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None): .. [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. - https://doi.org/10.1175/1520-0469(1972)029<0959:AOTSS>2.0.CO;2. + :doi:`10.1175/1520-0469(1972)029<0959:AOTSS>2.0.CO;2` ''' if surface_type is not None: From 2114c42cde5bc37901caeb7c1d79ee7824f617a5 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Sun, 28 Jan 2024 17:36:14 -0700 Subject: [PATCH 6/9] use math --- pvlib/irradiance.py | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index 845ed06f2b..2994e3ca75 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -554,6 +554,14 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None): ''' 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} + + where :math:`\rho` is albedo and :math:`\beta` is ``surface_tilt``. + Parameters ---------- surface_tilt : numeric @@ -583,9 +591,7 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None): Notes ----- - Ground diffuse irradiance is the the last term of equations 3, 4, 7, 8, - 10, 11, and 12 in [1]_. Table of albedo values by ``surface_type`` - are from [2]_, [3]_, [4]_; + Table of albedo values by ``surface_type`` are from [2]_, [3]_, [4]_; see :py:data:`~pvlib.irradiance.SURFACE_ALBEDOS`. References From 5bcb727cf87e2324c01960b4e65df6e5c1d9a31f Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Sun, 28 Jan 2024 17:39:43 -0700 Subject: [PATCH 7/9] use math --- pvlib/irradiance.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index 2994e3ca75..83b0d1bd7f 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -558,7 +558,7 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None): .. math:: - G_{ground} = GHI \times \rho \times \frac{1 - \cos \beta}{2} + G_{ground} = GHI \times \rho \times \frac{1 - \cos\beta}{2} where :math:`\rho` is albedo and :math:`\beta` is ``surface_tilt``. From 043f5edff9792ce20f5ce3ed80162472a3eddb2a Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Sun, 28 Jan 2024 17:41:54 -0700 Subject: [PATCH 8/9] r --- pvlib/irradiance.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index 83b0d1bd7f..1d7767232d 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -551,7 +551,7 @@ def poa_components(aoi, dni, poa_sky_diffuse, poa_ground_diffuse): def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None): - ''' + r''' Estimate diffuse irradiance on a tilted surface from ground reflections. Ground diffuse irradiance is calculated as From 3e4d8f7632822ee51bb9ef9c5bba819aa3f79f1e Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Mon, 29 Jan 2024 08:34:53 -0700 Subject: [PATCH 9/9] Update pvlib/irradiance.py Co-authored-by: Kevin Anderson --- pvlib/irradiance.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index 1d7767232d..a36e99d3c3 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -560,7 +560,7 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None): G_{ground} = GHI \times \rho \times \frac{1 - \cos\beta}{2} - where :math:`\rho` is albedo and :math:`\beta` is ``surface_tilt``. + where :math:`\rho` is ``albedo`` and :math:`\beta` is ``surface_tilt``. Parameters ----------