Add albedo function for inland water bodies

docs/sphinx/source/reference/irradiance/albedo.rst

@@ -0,0 +1,9 @@
+.. currentmodule:: pvlib
+
+Albedo
+------
+
+.. autosummary::
+   :toctree: ../generated/
+
+   albedo.albedo_water

docs/sphinx/source/reference/irradiance/index.rst

@@ -11,3 +11,4 @@ Irradiance
    transposition
    decomposition
    clearness-index
+   albedo

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

@@ -23,7 +23,9 @@ Enhancements
   shade perpendicular to ``axis_azimuth``. The function is applicable to both
   fixed-tilt and one-axis tracking systems.
   (:issue:`1689`, :pull:`1725`, :pull:`1962`)
-
+* Add function :py:func:`pvlib.albedo.albedo_water`, to calculate the
+  albedo for inland water bodies.
+  (:pull:`2079`)
 
 Bug fixes
 ~~~~~~~~~
@@ -46,3 +48,4 @@ Contributors
 * Cliff Hansen (:ghuser:`cwhanse`)
 * Mark Mikofski (:ghuser:`mikofski`)
 * Siddharth Kaul (:ghuser:`k10blogger`)
+* Ioannis Sifnaios (:ghuser:`IoannisSifnaios`)

pvlib/__init__.py

@@ -4,6 +4,7 @@
     # list spectrum first so it's available for atmosphere & pvsystem (GH 1628)
     spectrum,
 
+    albedo,
     atmosphere,
     bifacial,
     clearsky,

pvlib/albedo.py

@@ -0,0 +1,103 @@
+"""
+The ``albedo`` module contains functions for modeling albedo.
+"""
+
+from pvlib.tools import sind
+
+WATER_COLOR_COEFFS = {
+    'clear_water_no_waves': 0.13,
+    'clear_water_ripples_up_to_2.5cm': 0.16,
+    'clear_water_ripples_larger_than_2.5cm_occasional_whitecaps': 0.23,
+    'clear_water_frequent_whitecaps': 0.3,
+    'green_water_ripples_up_to_2.5cm': 0.22,
+    'muddy_water_no_waves': 0.19
+}
+
+WATER_ROUGHNESS_COEFFS = {
+    'clear_water_no_waves': 0.29,
+    'clear_water_ripples_up_to_2.5cm': 0.7,
+    'clear_water_ripples_larger_than_2.5cm_occasional_whitecaps': 1.23,
+    'clear_water_frequent_whitecaps': 2,
+    'green_water_ripples_up_to_2.5cm': 0.7,
+    'muddy_water_no_waves': 0.29
+}
+
+
+def albedo_water(solar_elevation, color_coeff=None, wave_roughness_coeff=None,
+                 surface_condition=None):
+    r"""
+    Estimation of albedo for inland water bodies.
+
+    The available surface conditions are for inland water bodies, e.g., lakes
+    and ponds. For ocean/open sea, an albedo value of 0.06 is recommended.
+    See :const:`pvlib.irradiance.SURFACE_ALBEDOS`.
+
+    Parameters
+    ----------
+    solar_elevation : numeric
+        Sun elevation angle. [degrees]
+
+    color_coeff : float, optional
+        Water color coefficient. [-]
+
+    wave_roughness_coeff : float, optional
+        Water wave roughness coefficient. [-]
+
+    surface_condition : string, optional
+        If supplied, overrides ``color_coeff`` and ``wave_roughness_coeff``.
+        ``surface_condition`` can be one of the following:
+        'clear_water_no_waves', 'clear_water_ripples_up_to_2.5cm',
+        'clear_water_ripples_larger_than_2.5cm_occasional_whitecaps',
+        'clear_water_frequent_whitecaps', 'green_water_ripples_up_to_2.5cm',
+        'muddy_water_no_waves'.
+
+    Returns
+    -------
+    albedo : numeric
+        Albedo for inland water bodies.
+
+    Notes
+    -----
+    The equation for calculating the albedo :math:`\rho` is given by
+
+    .. math::
+       :label: albedo
+
+        \rho = c^{(r sin(\alpha) + 1)}
+
+    Inputs to the model are the water color coefficient :math:`c` [-], the
+    water wave roughness coefficient :math:`r` [-] and the solar elevation
+    :math:`\alpha` [degrees]. Parameters are provided in [1]_ , and are coded
+    for convenience in :data:`~pvlib.albedo.WATER_COLOR_COEFFS` and
+    :data:`~pvlib.albedo.WATER_ROUGHNESS_COEFFS`. The values of these
+    coefficients are experimentally determined.
+
+    +---------------------------------------------------------------+-------------------------------+----------------------------------------+
+    | Surface and condition                                         | Color coefficient (:math:`c`) | Wave roughness coefficient (:math:`r`) |
+    +===============================================================+===============================+========================================+
+    | Clear water no waves                                          | 0.13                          | 0.29                                   |
+    +---------------------------------------------------------------+-------------------------------+----------------------------------------+
+    | Clear water ripples up to 2.5 cm                              | 0.16                          | 0.70                                   |
+    +---------------------------------------------------------------+-------------------------------+----------------------------------------+
+    | Clear water ripples larger than 2.5 cm (occasional whitecaps) | 0.23                          | 1.23                                   |
+    +---------------------------------------------------------------+-------------------------------+----------------------------------------+
+    | Clear water frequent whitecaps                                | 0.30                          | 2.00                                   |
+    +---------------------------------------------------------------+-------------------------------+----------------------------------------+
+    | Green water ripples up to 2.5cm                               | 0.22                          | 0.70                                   |
+    +---------------------------------------------------------------+-------------------------------+----------------------------------------+
+    | Muddy water no waves                                          | 0.19                          | 0.29                                   |
+    +---------------------------------------------------------------+-------------------------------+----------------------------------------+
+
+    References
+    ----------
+    .. [1] Dvoracek M.J., Hannabas B. (1990). "Prediction of albedo for use in
+       evapotranspiration and irrigation scheduling." IN: Visions of the Future
+       American Society of Agricultural Engineers 04-90: 692-699.
+    """  # noqa: E501
+
+    if surface_condition is not None:
+        color_coeff = WATER_COLOR_COEFFS[surface_condition]
+        wave_roughness_coeff = WATER_ROUGHNESS_COEFFS[surface_condition]
+
+    albedo = color_coeff ** (wave_roughness_coeff * sind(solar_elevation) + 1)
+    return albedo

pvlib/tests/test_albedo.py

@@ -0,0 +1,43 @@
+import numpy as np
+import pandas as pd
+from pvlib import albedo
+
+from .conftest import assert_series_equal
+from numpy.testing import assert_allclose
+
+
+def test_albedo_water_default():
+    result = albedo.albedo_water(solar_elevation=90,
+                                 color_coeff=0.13,
+                                 wave_roughness_coeff=0.29)
+    assert_allclose(result, 0.072, 0.001)
+
+
+def test_albedo_water_string_surface_condition():
+    result = albedo.albedo_water(solar_elevation=90,
+                                 surface_condition='clear_water_no_waves')
+    assert_allclose(result, 0.072, 0.001)
+
+
+def test_albedo_water_ndarray():
+    solar_elevs = np.array([0, 20, 60, 90])
+    color_coeffs = np.array([0.1, 0.2, 0.3, 0.4])
+    roughness_coeffs = np.array([0.3, 0.8, 1.5, 2])
+    result = albedo.albedo_water(solar_elevation=solar_elevs,
+                                 color_coeff=color_coeffs,
+                                 wave_roughness_coeff=roughness_coeffs)
+    expected = np.array([0.1, 0.12875, 0.06278, 0.064])
+    assert_allclose(expected, result, atol=1e-5)
+
+
+def test_albedo_water_series():
+    times = pd.date_range(start="2015-01-01 00:00", end="2015-01-01 18:00",
+                          freq="6h")
+    solar_elevs = pd.Series([0, 20, 60, 90], index=times)
+    color_coeffs = pd.Series([0.1, 0.2, 0.3, 0.4], index=times)
+    roughness_coeffs = pd.Series([0.3, 0.8, 1.5, 2], index=times)
+    result = albedo.albedo_water(solar_elevation=solar_elevs,
+                                 color_coeff=color_coeffs,
+                                 wave_roughness_coeff=roughness_coeffs)
+    expected = pd.Series([0.1, 0.12875, 0.06278, 0.064], index=times)
+    assert_series_equal(expected, result, atol=1e-5)