Skip to content

Improve docstring for get_ground_diffuse #1953

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Feb 27, 2024
Merged

Improve docstring for get_ground_diffuse #1953

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
d0173e1
improve docstring for get_ground_diffuse
cwhanse Jan 26, 2024
5f23a6e
fix formatting. Reduce description text. Whatsnew
cwhanse Jan 26, 2024
1bd9fb8
try to get the sphinx reference
cwhanse Jan 26, 2024
ea83426
sphinx reference
cwhanse Jan 26, 2024
43c346f
use doi
cwhanse Jan 26, 2024
2114c42
use math
cwhanse Jan 29, 2024
5bcb727
use math
cwhanse Jan 29, 2024
043f5ed
r
cwhanse Jan 29, 2024
3e4d8f7
Update pvlib/irradiance.py
cwhanse Jan 29, 2024
2e4f2f2
Merge branch 'main' into ref_ground_diffuse
cwhanse Feb 1, 2024
816a8f8
Merge branch 'main' into ref_ground_diffuse
cwhanse Feb 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/sphinx/source/whatsnew/v0.10.4.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Testing

Documentation
~~~~~~~~~~~~~

* Improved references and description for :py:func:`~pvlib.irradiance.get_ground_diffuse`. (:pull:`1953`)

Requirements
~~~~~~~~~~~~
Expand All @@ -29,3 +29,4 @@ Requirements
Contributors
~~~~~~~~~~~~
* :ghuser:`matsuobasho`
* :ghuser:`cwhanse`
33 changes: 15 additions & 18 deletions pvlib/irradiance.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
----------
Expand All @@ -567,13 +562,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
Expand All @@ -584,23 +579,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 by ``surface_type``
Copy link
Member

@adriesse adriesse Jan 28, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you describe what that last term is, rather than refer to a paper that's not openly accessible?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a preprint here but one has to find it by searching the title.

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
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:
Expand Down