From 0e873254eee0a76d4ecdcfa06dbfc32275e42602 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Thu, 6 Jun 2024 12:16:41 +0200
Subject: [PATCH 01/30] Albedo function

---
 .../source/reference/irradiance/albedo.rst    |   9 ++
 .../source/reference/irradiance/index.rst     |   1 +
 pvlib/__init__.py                             |   1 +
 pvlib/albedo.py                               | 105 ++++++++++++++++++
 pvlib/tests/test_albedo.py                    |  43 +++++++
 5 files changed, 159 insertions(+)
 create mode 100644 docs/sphinx/source/reference/irradiance/albedo.rst
 create mode 100644 pvlib/albedo.py
 create mode 100644 pvlib/tests/test_albedo.py

diff --git a/docs/sphinx/source/reference/irradiance/albedo.rst b/docs/sphinx/source/reference/irradiance/albedo.rst
new file mode 100644
index 0000000000..27c9bbb2f8
--- /dev/null
+++ b/docs/sphinx/source/reference/irradiance/albedo.rst
@@ -0,0 +1,9 @@
+.. currentmodule:: pvlib
+
+Albedo
+------
+
+.. autosummary::
+   :toctree: ../generated/
+
+   albedo.albedo_water
diff --git a/docs/sphinx/source/reference/irradiance/index.rst b/docs/sphinx/source/reference/irradiance/index.rst
index 2263a2d2c1..72064cccbc 100644
--- a/docs/sphinx/source/reference/irradiance/index.rst
+++ b/docs/sphinx/source/reference/irradiance/index.rst
@@ -11,3 +11,4 @@ Irradiance
    transposition
    decomposition
    clearness-index
+   albedo
diff --git a/pvlib/__init__.py b/pvlib/__init__.py
index 413af8f607..b5b07866a4 100644
--- a/pvlib/__init__.py
+++ b/pvlib/__init__.py
@@ -4,6 +4,7 @@
     # list spectrum first so it's available for atmosphere & pvsystem (GH 1628)
     spectrum,
 
+    albedo,
     atmosphere,
     bifacial,
     clearsky,
diff --git a/pvlib/albedo.py b/pvlib/albedo.py
new file mode 100644
index 0000000000..b4023bbe0d
--- /dev/null
+++ b/pvlib/albedo.py
@@ -0,0 +1,105 @@
+"""
+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 values 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 :py:constant:`pvlib.temperature.ALBEDO`.
+
+    Parameters
+    ----------
+    solar_elevation : numeric
+        Sun elevation angle. [degrees]
+
+    color_coeff : numeric, optional
+        Water color coefficient. [-]
+
+    wave_roughness_coeff : numeric, 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
+    -------
+    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
diff --git a/pvlib/tests/test_albedo.py b/pvlib/tests/test_albedo.py
new file mode 100644
index 0000000000..501c262d60
--- /dev/null
+++ b/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])
+    color_coeffs = np.array([0.1, 0.25, 0.4])
+    roughness_coeffs = np.array([0.3, 1.3, 2.3])
+    result = albedo.albedo_water(solar_elevation=solar_elevs,
+                                 color_coeff=color_coeffs,
+                                 wave_roughness_coeff=roughness_coeffs)
+    expected = np.array([0.1, 0.1349, 0.0644])
+    assert_allclose(expected, result, 3)
+
+
+def test_lindholm_floating_series():
+    times = pd.date_range(start="2015-01-01 00:00", end="2015-01-01 12:00",
+                          freq="6h")
+    solar_elevs = pd.Series([0, 20, 60], index=times)
+    color_coeffs = pd.Series([0.1, 0.25, 0.4], index=times)
+    roughness_coeffs = pd.Series([0.3, 1.3, 2.3], 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.134973, 0.064479], index=times)
+    assert_series_equal(expected, result, atol=1e-5)

From 163cf82c13a94d01447616dc33d7b39b983b29cd Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Thu, 6 Jun 2024 12:28:33 +0200
Subject: [PATCH 02/30] fixed test tolerance

---
 pvlib/tests/test_albedo.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pvlib/tests/test_albedo.py b/pvlib/tests/test_albedo.py
index 501c262d60..9ec6d20032 100644
--- a/pvlib/tests/test_albedo.py
+++ b/pvlib/tests/test_albedo.py
@@ -26,8 +26,8 @@ def test_albedo_water_ndarray():
     result = albedo.albedo_water(solar_elevation=solar_elevs,
                                  color_coeff=color_coeffs,
                                  wave_roughness_coeff=roughness_coeffs)
-    expected = np.array([0.1, 0.1349, 0.0644])
-    assert_allclose(expected, result, 3)
+    expected = np.array([0.1, 0.134973, 0.064479])
+    assert_allclose(expected, result, atol=1e-5)
 
 
 def test_lindholm_floating_series():

From 47efb47f560d930cc58ca0170b1441a7efd6135f Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Thu, 6 Jun 2024 12:39:43 +0200
Subject: [PATCH 03/30] fix linter

---
 pvlib/albedo.py | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index b4023bbe0d..6a796bb4b6 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -11,7 +11,7 @@
     '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,
@@ -20,7 +20,7 @@
     '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,
@@ -52,7 +52,7 @@ def albedo_water(solar_elevation, color_coeff=None, wave_roughness_coeff=None,
         * 'clear_water_frequent_whitecaps'
         * 'green_water_ripples_up_to_2.5cm'
         * 'muddy_water_no_waves'.
-        
+
     Returns
     -------
     numeric
@@ -66,12 +66,12 @@ def albedo_water(solar_elevation, color_coeff=None, wave_roughness_coeff=None,
        :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 
+    for convenience in :data:`~pvlib.albedo.WATER_COLOR_COEFFS` and
+    :data:`~pvlib.albedo.WATER_ROUGHNESS_COEFFS`. The values of these
     coefficients are experimentally determined.
 
     +---------------------------------------------------------------+-----------------------------+--------------------------------------+
@@ -92,7 +92,7 @@ def albedo_water(solar_elevation, color_coeff=None, wave_roughness_coeff=None,
 
     References
     ----------
-    .. [1] Dvoracek M.J., Hannabas B. (1990). "Prediction of albedo for use in 
+    .. [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

From 7e44696e04a47a3a7832d8923c547c45e04d7bb6 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Thu, 6 Jun 2024 12:52:41 +0200
Subject: [PATCH 04/30] changed format of function description

---
 pvlib/albedo.py | 52 ++++++++++++++++++++++++-------------------------
 1 file changed, 25 insertions(+), 27 deletions(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index 6a796bb4b6..2ae35e6f67 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -26,37 +26,35 @@
 def albedo_water(solar_elevation, color_coeff=None, wave_roughness_coeff=None,
                  surface_condition=None):
     r"""
-    Estimation of albedo values for inland water bodies.
+    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 :py:constant:`pvlib.temperature.ALBEDO`.
+    See :const:`pvlib.irradiance.SURFACE_ALBEDOS`.
 
     Parameters
     ----------
     solar_elevation : numeric
         Sun elevation angle. [degrees]
 
-    color_coeff : numeric, optional
+    color_coeff : float, optional
         Water color coefficient. [-]
 
-    wave_roughness_coeff : numeric, optional
+    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'.
+        '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
     -------
-    numeric
-    Albedo for inland water bodies.
+    albedo : numeric
+        Albedo for inland water bodies.
 
     Notes
     -----
@@ -74,21 +72,21 @@ def albedo_water(solar_elevation, color_coeff=None, wave_roughness_coeff=None,
     :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                                 |
-    +---------------------------------------------------------------+-----------------------------+--------------------------------------+
+    +---------------------------------------------------------------+-------------------------------+----------------------------------------+
+    | 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
     ----------

From c3c2fc12cf48a1f0525b6faa767d479021c30729 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Thu, 6 Jun 2024 13:01:10 +0200
Subject: [PATCH 05/30] update watsnew

---
 docs/sphinx/source/whatsnew/v0.11.0.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/sphinx/source/whatsnew/v0.11.0.rst b/docs/sphinx/source/whatsnew/v0.11.0.rst
index 37cbad3bf9..c0a58616f8 100644
--- a/docs/sphinx/source/whatsnew/v0.11.0.rst
+++ b/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`)

From 357cb38a37eba91c3f5b87152c131b7daada4c18 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Thu, 6 Jun 2024 16:39:18 +0200
Subject: [PATCH 06/30] Update test_albedo.py

---
 pvlib/tests/test_albedo.py | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/pvlib/tests/test_albedo.py b/pvlib/tests/test_albedo.py
index 9ec6d20032..8a9997b358 100644
--- a/pvlib/tests/test_albedo.py
+++ b/pvlib/tests/test_albedo.py
@@ -20,24 +20,24 @@ def test_albedo_water_string_surface_condition():
 
 
 def test_albedo_water_ndarray():
-    solar_elevs = np.array([0, 20, 60])
-    color_coeffs = np.array([0.1, 0.25, 0.4])
-    roughness_coeffs = np.array([0.3, 1.3, 2.3])
+    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.134973, 0.064479])
+    expected = np.array([0.1, 0.1287, 0.0627, 0.064])
     assert_allclose(expected, result, atol=1e-5)
 
 
-def test_lindholm_floating_series():
-    times = pd.date_range(start="2015-01-01 00:00", end="2015-01-01 12:00",
+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], index=times)
-    color_coeffs = pd.Series([0.1, 0.25, 0.4], index=times)
-    roughness_coeffs = pd.Series([0.3, 1.3, 2.3], index=times)
+    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.134973, 0.064479], index=times)
+    expected = pd.Series([0.1, 0.1287, 0.0627, 0.064], index=times)
     assert_series_equal(expected, result, atol=1e-5)

From 55b92714ebbd04873dff2d7fd365d15d05f414be Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Thu, 6 Jun 2024 16:52:25 +0200
Subject: [PATCH 07/30] Update test_albedo.py

---
 pvlib/tests/test_albedo.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pvlib/tests/test_albedo.py b/pvlib/tests/test_albedo.py
index 8a9997b358..c227cc22d9 100644
--- a/pvlib/tests/test_albedo.py
+++ b/pvlib/tests/test_albedo.py
@@ -26,7 +26,7 @@ def test_albedo_water_ndarray():
     result = albedo.albedo_water(solar_elevation=solar_elevs,
                                  color_coeff=color_coeffs,
                                  wave_roughness_coeff=roughness_coeffs)
-    expected = np.array([0.1, 0.1287, 0.0627, 0.064])
+    expected = np.array([0.1, 0.12875, 0.06278, 0.064])
     assert_allclose(expected, result, atol=1e-5)
 
 
@@ -39,5 +39,5 @@ def test_albedo_water_series():
     result = albedo.albedo_water(solar_elevation=solar_elevs,
                                  color_coeff=color_coeffs,
                                  wave_roughness_coeff=roughness_coeffs)
-    expected = pd.Series([0.1, 0.1287, 0.0627, 0.064], index=times)
+    expected = pd.Series([0.1, 0.12875, 0.06278, 0.064], index=times)
     assert_series_equal(expected, result, atol=1e-5)

From 187b6f67f6bf8835172d054557950e230f413f10 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com>
Date: Mon, 10 Jun 2024 19:21:34 +0200
Subject: [PATCH 08/30] Update pvlib/albedo.py

Co-authored-by: Kevin Anderson <kevin.anderso@gmail.com>
---
 pvlib/albedo.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index 2ae35e6f67..2d9b550ab7 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -16,7 +16,7 @@
 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_ripples_larger_than_2.5cm_occasional_whitecaps': 1.25,
     'clear_water_frequent_whitecaps': 2,
     'green_water_ripples_up_to_2.5cm': 0.7,
     'muddy_water_no_waves': 0.29

From 2a20e8c166454017ec504b5e685083a18d13813b Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com>
Date: Mon, 10 Jun 2024 19:23:30 +0200
Subject: [PATCH 09/30] Update pvlib/albedo.py

Update table format

Co-authored-by: Kevin Anderson <kevin.anderso@gmail.com>
---
 pvlib/albedo.py | 35 +++++++++++++++++++++--------------
 1 file changed, 21 insertions(+), 14 deletions(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index 2d9b550ab7..59275d62f1 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -73,20 +73,27 @@ def albedo_water(solar_elevation, color_coeff=None, wave_roughness_coeff=None,
     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                                   |
-    +---------------------------------------------------------------+-------------------------------+----------------------------------------+
+    +------------------------+-------------------+-------------------------+
+    | Surface and condition  | Color coefficient | Wave roughness          |
+    |                        | (:math:`c`)       | coefficient (:math:`r`) |
+    +========================+===================+=========================+
+    | Clear water, no waves  | 0.13              | 0.29                    |
+    +------------------------+-------------------+-------------------------+
+    | Clear water, ripples   | 0.16              | 0.70                    |
+    | up to 2.5 cm           |                   |                         |
+    +------------------------+-------------------+-------------------------+
+    | Clear water, ripples   | 0.23              | 1.25                    |
+    | larger than 2.5 cm     |                   |                         |
+    | (occasional whitecaps) |                   |                         |
+    +------------------------+-------------------+-------------------------+
+    | Clear water,           | 0.30              | 2.00                    |
+    | frequent whitecaps     |                   |                         |
+    +------------------------+-------------------+-------------------------+
+    | Green water, ripples   | 0.22              | 0.70                    |
+    | up to 2.5cm            |                   |                         |
+    +------------------------+-------------------+-------------------------+
+    | Muddy water, no waves  | 0.19              | 0.29                    |
+    +------------------------+-------------------+-------------------------+
 
     References
     ----------

From 75ae1428f363069e1d05487a78024e92f784f780 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com>
Date: Mon, 10 Jun 2024 19:38:09 +0200
Subject: [PATCH 10/30] Update pvlib/albedo.py

Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com>
---
 pvlib/albedo.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index 59275d62f1..3ffc5cb22e 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -72,7 +72,6 @@ def albedo_water(solar_elevation, color_coeff=None, wave_roughness_coeff=None,
     :data:`~pvlib.albedo.WATER_ROUGHNESS_COEFFS`. The values of these
     coefficients are experimentally determined.
 
-    +---------------------------------------------------------------+-------------------------------+----------------------------------------+
     +------------------------+-------------------+-------------------------+
     | Surface and condition  | Color coefficient | Wave roughness          |
     |                        | (:math:`c`)       | coefficient (:math:`r`) |

From 5c93bfe5899cf366d7a2f4c6204f1bbcb8fd7fb8 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Mon, 10 Jun 2024 19:52:59 +0200
Subject: [PATCH 11/30] Reviewers' comments

---
 .../source/reference/irradiance/albedo.rst      |  2 +-
 pvlib/albedo.py                                 | 17 ++++++++++-------
 2 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/docs/sphinx/source/reference/irradiance/albedo.rst b/docs/sphinx/source/reference/irradiance/albedo.rst
index 27c9bbb2f8..868a065d1a 100644
--- a/docs/sphinx/source/reference/irradiance/albedo.rst
+++ b/docs/sphinx/source/reference/irradiance/albedo.rst
@@ -6,4 +6,4 @@ Albedo
 .. autosummary::
    :toctree: ../generated/
 
-   albedo.albedo_water
+   albedo.inland_water_dvoracek
diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index 3ffc5cb22e..7689090843 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -23,8 +23,8 @@
 }
 
 
-def albedo_water(solar_elevation, color_coeff=None, wave_roughness_coeff=None,
-                 surface_condition=None):
+def inland_water_dvoracek(solar_elevation, surface_condition=None,
+                          color_coeff=None, wave_roughness_coeff=None):
     r"""
     Estimation of albedo for inland water bodies.
 
@@ -46,10 +46,13 @@ def albedo_water(solar_elevation, color_coeff=None, wave_roughness_coeff=None,
     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'.
+
+        * '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
     -------
@@ -99,7 +102,7 @@ def albedo_water(solar_elevation, color_coeff=None, wave_roughness_coeff=None,
     .. [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]

From e487893ce9867156116296e18adbb484949dbc19 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Mon, 10 Jun 2024 21:44:00 +0200
Subject: [PATCH 12/30] Reviewer's comments vol.2

---
 pvlib/albedo.py            | 22 +++++++++++++++-------
 pvlib/tests/test_albedo.py | 33 ++++++++++++++++++++-------------
 2 files changed, 35 insertions(+), 20 deletions(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index 7689090843..409512a657 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -3,6 +3,7 @@
 """
 
 from pvlib.tools import sind
+import numpy as np
 
 WATER_COLOR_COEFFS = {
     'clear_water_no_waves': 0.13,
@@ -37,12 +38,6 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
     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:
@@ -54,6 +49,12 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
         * 'green_water_ripples_up_to_2.5cm'
         * 'muddy_water_no_waves'.
 
+    color_coeff : float, optional
+        Water color coefficient. [-]
+
+    wave_roughness_coeff : float, optional
+        Water wave roughness coefficient. [-]
+
     Returns
     -------
     albedo : numeric
@@ -104,9 +105,16 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
        American Society of Agricultural Engineers 04-90: 692-699.
     """
 
-    if surface_condition is not None:
+    if surface_condition is None:
+        if (color_coeff is None) or (wave_roughness_coeff is None):
+            raise ValueError('Either a surface_condition has to be chosen or a'
+                             'combination of both color and wave roughness'
+                             'coefficients.')
+    else:
         color_coeff = WATER_COLOR_COEFFS[surface_condition]
         wave_roughness_coeff = WATER_ROUGHNESS_COEFFS[surface_condition]
 
+    solar_elevation = np.where(solar_elevation < 0, 0, solar_elevation)
+
     albedo = color_coeff ** (wave_roughness_coeff * sind(solar_elevation) + 1)
     return albedo
diff --git a/pvlib/tests/test_albedo.py b/pvlib/tests/test_albedo.py
index c227cc22d9..f7b516b6ed 100644
--- a/pvlib/tests/test_albedo.py
+++ b/pvlib/tests/test_albedo.py
@@ -7,37 +7,44 @@
 
 
 def test_albedo_water_default():
-    result = albedo.albedo_water(solar_elevation=90,
+    result = albedo.inland_water_dvoracek(solar_elevation=90,
                                  color_coeff=0.13,
                                  wave_roughness_coeff=0.29)
     assert_allclose(result, 0.072, 0.001)
 
 
+def test_albedo_water_negative_elevation():
+    result = albedo.inland_water_dvoracek(solar_elevation=-60,
+                                 color_coeff=0.13,
+                                 wave_roughness_coeff=0.29)
+    assert_allclose(result, 0.13, 0.01)
+
+
 def test_albedo_water_string_surface_condition():
-    result = albedo.albedo_water(solar_elevation=90,
+    result = albedo.inland_water_dvoracek(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,
+    solar_elevs = np.array([-50, 0, 20, 60, 90])
+    color_coeffs = np.array([0.1, 0.1, 0.2, 0.3, 0.4])
+    roughness_coeffs = np.array([0.3, 0.3, 0.8, 1.5, 2])
+    result = albedo.inland_water_dvoracek(solar_elevation=solar_elevs,
                                  color_coeff=color_coeffs,
                                  wave_roughness_coeff=roughness_coeffs)
-    expected = np.array([0.1, 0.12875, 0.06278, 0.064])
+    expected = np.array([0.1, 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",
+    times = pd.date_range(start="2015-01-01 00:00", end="2015-01-02 00: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,
+    solar_elevs = pd.Series([-50, 0, 20, 60, 90], index=times)
+    color_coeffs = pd.Series([0.1, 0.1, 0.2, 0.3, 0.4], index=times)
+    roughness_coeffs = pd.Series([0.1, 0.3, 0.8, 1.5, 2], index=times)
+    result = albedo.inland_water_dvoracek(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)
+    expected = pd.Series([0.1, 0.1, 0.12875, 0.06278, 0.064], index=times)
     assert_series_equal(expected, result, atol=1e-5)

From b5cef904e1c5bad9b6ace98392e063f5a90b747f Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Mon, 10 Jun 2024 21:54:23 +0200
Subject: [PATCH 13/30] Update v0.11.0.rst

---
 docs/sphinx/source/whatsnew/v0.11.0.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/sphinx/source/whatsnew/v0.11.0.rst b/docs/sphinx/source/whatsnew/v0.11.0.rst
index c0a58616f8..9a3987c9dd 100644
--- a/docs/sphinx/source/whatsnew/v0.11.0.rst
+++ b/docs/sphinx/source/whatsnew/v0.11.0.rst
@@ -23,7 +23,7 @@ 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
+* Add function :py:func:`pvlib.albedo.inland_water_dvoracek`, to calculate the
   albedo for inland water bodies.
   (:pull:`2079`)
 

From 0e5b464bcc9b94a405247c86fff4fbde2919a7dd Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Mon, 10 Jun 2024 22:04:03 +0200
Subject: [PATCH 14/30] fixed linter

---
 pvlib/tests/test_albedo.py | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/pvlib/tests/test_albedo.py b/pvlib/tests/test_albedo.py
index f7b516b6ed..1f6f5e8fe8 100644
--- a/pvlib/tests/test_albedo.py
+++ b/pvlib/tests/test_albedo.py
@@ -8,21 +8,22 @@
 
 def test_albedo_water_default():
     result = albedo.inland_water_dvoracek(solar_elevation=90,
-                                 color_coeff=0.13,
-                                 wave_roughness_coeff=0.29)
+                                          color_coeff=0.13,
+                                          wave_roughness_coeff=0.29)
     assert_allclose(result, 0.072, 0.001)
 
 
 def test_albedo_water_negative_elevation():
     result = albedo.inland_water_dvoracek(solar_elevation=-60,
-                                 color_coeff=0.13,
-                                 wave_roughness_coeff=0.29)
+                                          color_coeff=0.13,
+                                          wave_roughness_coeff=0.29)
     assert_allclose(result, 0.13, 0.01)
 
 
 def test_albedo_water_string_surface_condition():
     result = albedo.inland_water_dvoracek(solar_elevation=90,
-                                 surface_condition='clear_water_no_waves')
+                                          surface_condition=
+                                          'clear_water_no_waves')
     assert_allclose(result, 0.072, 0.001)
 
 
@@ -31,8 +32,9 @@ def test_albedo_water_ndarray():
     color_coeffs = np.array([0.1, 0.1, 0.2, 0.3, 0.4])
     roughness_coeffs = np.array([0.3, 0.3, 0.8, 1.5, 2])
     result = albedo.inland_water_dvoracek(solar_elevation=solar_elevs,
-                                 color_coeff=color_coeffs,
-                                 wave_roughness_coeff=roughness_coeffs)
+                                          color_coeff=color_coeffs,
+                                          wave_roughness_coeff=
+                                          roughness_coeffs)
     expected = np.array([0.1, 0.1, 0.12875, 0.06278, 0.064])
     assert_allclose(expected, result, atol=1e-5)
 
@@ -44,7 +46,8 @@ def test_albedo_water_series():
     color_coeffs = pd.Series([0.1, 0.1, 0.2, 0.3, 0.4], index=times)
     roughness_coeffs = pd.Series([0.1, 0.3, 0.8, 1.5, 2], index=times)
     result = albedo.inland_water_dvoracek(solar_elevation=solar_elevs,
-                                 color_coeff=color_coeffs,
-                                 wave_roughness_coeff=roughness_coeffs)
+                                          color_coeff=color_coeffs,
+                                          wave_roughness_coeff=
+                                          roughness_coeffs)
     expected = pd.Series([0.1, 0.1, 0.12875, 0.06278, 0.064], index=times)
     assert_series_equal(expected, result, atol=1e-5)

From 0340389e42a1a6769273832ee1b4e8dd566d2430 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Mon, 10 Jun 2024 22:12:07 +0200
Subject: [PATCH 15/30] fixed linter vol.2

---
 pvlib/tests/test_albedo.py | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/pvlib/tests/test_albedo.py b/pvlib/tests/test_albedo.py
index 1f6f5e8fe8..84f54be3ad 100644
--- a/pvlib/tests/test_albedo.py
+++ b/pvlib/tests/test_albedo.py
@@ -22,8 +22,7 @@ def test_albedo_water_negative_elevation():
 
 def test_albedo_water_string_surface_condition():
     result = albedo.inland_water_dvoracek(solar_elevation=90,
-                                          surface_condition=
-                                          'clear_water_no_waves')
+                                          surface_condition='clear_water_no_waves')   # noqa: E501
     assert_allclose(result, 0.072, 0.001)
 
 
@@ -33,8 +32,7 @@ def test_albedo_water_ndarray():
     roughness_coeffs = np.array([0.3, 0.3, 0.8, 1.5, 2])
     result = albedo.inland_water_dvoracek(solar_elevation=solar_elevs,
                                           color_coeff=color_coeffs,
-                                          wave_roughness_coeff=
-                                          roughness_coeffs)
+                                          wave_roughness_coeff=roughness_coeffs)   # noqa: E501
     expected = np.array([0.1, 0.1, 0.12875, 0.06278, 0.064])
     assert_allclose(expected, result, atol=1e-5)
 
@@ -47,7 +45,6 @@ def test_albedo_water_series():
     roughness_coeffs = pd.Series([0.1, 0.3, 0.8, 1.5, 2], index=times)
     result = albedo.inland_water_dvoracek(solar_elevation=solar_elevs,
                                           color_coeff=color_coeffs,
-                                          wave_roughness_coeff=
-                                          roughness_coeffs)
+                                          wave_roughness_coeff=roughness_coeffs)   # noqa: E501
     expected = pd.Series([0.1, 0.1, 0.12875, 0.06278, 0.064], index=times)
     assert_series_equal(expected, result, atol=1e-5)

From f469db3136d2bbd0cdd18fd30b56e0f93ed5313e Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Mon, 10 Jun 2024 22:24:13 +0200
Subject: [PATCH 16/30] Added test raising a ValueError

---
 pvlib/tests/test_albedo.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/pvlib/tests/test_albedo.py b/pvlib/tests/test_albedo.py
index 84f54be3ad..5d0b7606fe 100644
--- a/pvlib/tests/test_albedo.py
+++ b/pvlib/tests/test_albedo.py
@@ -1,5 +1,6 @@
 import numpy as np
 import pandas as pd
+import pytest
 from pvlib import albedo
 
 from .conftest import assert_series_equal
@@ -48,3 +49,8 @@ def test_albedo_water_series():
                                           wave_roughness_coeff=roughness_coeffs)   # noqa: E501
     expected = pd.Series([0.1, 0.1, 0.12875, 0.06278, 0.064], index=times)
     assert_series_equal(expected, result, atol=1e-5)
+
+
+def test_albedo_water_invalid():
+    with pytest.raises(ValueError):
+        albedo.inland_water_dvoracek(45)

From d2e83f3b6c930488d7244a1a9db04461f7d2d58d Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com>
Date: Tue, 11 Jun 2024 10:23:55 +0200
Subject: [PATCH 17/30] Update pvlib/albedo.py

Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com>
---
 pvlib/albedo.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index 409512a657..fd139ce0c5 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -30,8 +30,8 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
     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`.
+    and ponds. For ocean/open sea, see
+    :const:`pvlib.irradiance.SURFACE_ALBEDOS`.
 
     Parameters
     ----------

From c9ef6643ba153e62b4de7bc8485b75fef42d9e08 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com>
Date: Tue, 11 Jun 2024 10:24:09 +0200
Subject: [PATCH 18/30] Update pvlib/albedo.py

Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com>
---
 pvlib/albedo.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index fd139ce0c5..a223ad3155 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -58,7 +58,7 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
     Returns
     -------
     albedo : numeric
-        Albedo for inland water bodies.
+        Albedo for inland water bodies. [-]
 
     Notes
     -----

From 4a089aba85df8d2414c8e5c0c8540fd7bb386045 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com>
Date: Tue, 11 Jun 2024 10:24:27 +0200
Subject: [PATCH 19/30] Update pvlib/albedo.py

Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com>
---
 pvlib/albedo.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index a223ad3155..b102829559 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -67,7 +67,7 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
     .. math::
        :label: albedo
 
-        \rho = c^{(r sin(\alpha) + 1)}
+        \rho = c^{(r \cdot \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

From 75952161ab1417a5692f5421baa819fbdf4304e0 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Tue, 11 Jun 2024 10:38:45 +0200
Subject: [PATCH 20/30] More review comments

---
 pvlib/albedo.py            |  6 +++---
 pvlib/tests/test_albedo.py | 13 +++++++++++--
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index b102829559..180ac1c7c2 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -107,9 +107,9 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
 
     if surface_condition is None:
         if (color_coeff is None) or (wave_roughness_coeff is None):
-            raise ValueError('Either a surface_condition has to be chosen or a'
-                             'combination of both color and wave roughness'
-                             'coefficients.')
+            raise ValueError('Either a `surface_condition` has to be chosen or'
+                             ' a combination of `color_coeff` and'
+                             '`wave_roughness_coeff`.')
     else:
         color_coeff = WATER_COLOR_COEFFS[surface_condition]
         wave_roughness_coeff = WATER_ROUGHNESS_COEFFS[surface_condition]
diff --git a/pvlib/tests/test_albedo.py b/pvlib/tests/test_albedo.py
index 5d0b7606fe..bef2841ed6 100644
--- a/pvlib/tests/test_albedo.py
+++ b/pvlib/tests/test_albedo.py
@@ -52,5 +52,14 @@ def test_albedo_water_series():
 
 
 def test_albedo_water_invalid():
-    with pytest.raises(ValueError):
-        albedo.inland_water_dvoracek(45)
+    with pytest.raises(ValueError):  # no surface info given
+        albedo.inland_water_dvoracek(solar_elevation=45)
+    with pytest.raises(KeyError):  # invalid surface type
+        albedo.inland_water_dvoracek(solar_elevation=45,
+                                     surface_condition='not_a_surface_type')
+    with pytest.raises(ValueError):  # only one coefficient given
+        albedo.inland_water_dvoracek(solar_elevation=45,
+                                     color_coeff=0.13)
+    with pytest.raises(ValueError):  # only one coefficient given
+        albedo.inland_water_dvoracek(solar_elevation=45,
+                                     wave_roughness_coeff=0.29)

From 93b6ff8968891cd53a9b2c0a4b2fecaf30c925b8 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com>
Date: Tue, 11 Jun 2024 16:53:11 +0200
Subject: [PATCH 21/30] Update pvlib/albedo.py

Co-authored-by: Kevin Anderson <kevin.anderso@gmail.com>
---
 pvlib/albedo.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index 180ac1c7c2..239e293aa5 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -109,7 +109,7 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
         if (color_coeff is None) or (wave_roughness_coeff is None):
             raise ValueError('Either a `surface_condition` has to be chosen or'
                              ' a combination of `color_coeff` and'
-                             '`wave_roughness_coeff`.')
+                             ' `wave_roughness_coeff`.')
     else:
         color_coeff = WATER_COLOR_COEFFS[surface_condition]
         wave_roughness_coeff = WATER_ROUGHNESS_COEFFS[surface_condition]

From 7c99fd234d3de452178ce7be9c284ce2ca7042bf Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Tue, 11 Jun 2024 17:10:28 +0200
Subject: [PATCH 22/30] Reviewers' comments vol.3

---
 pvlib/albedo.py | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index 239e293aa5..a4983e2127 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -4,6 +4,8 @@
 
 from pvlib.tools import sind
 import numpy as np
+import pandas as pd
+
 
 WATER_COLOR_COEFFS = {
     'clear_water_no_waves': 0.13,
@@ -105,16 +107,29 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
        American Society of Agricultural Engineers 04-90: 692-699.
     """
 
-    if surface_condition is None:
-        if (color_coeff is None) or (wave_roughness_coeff is None):
-            raise ValueError('Either a `surface_condition` has to be chosen or'
-                             ' a combination of `color_coeff` and'
-                             ' `wave_roughness_coeff`.')
-    else:
+    if surface_condition is not None and (
+        color_coeff is None and wave_roughness_coeff is None
+    ):
+        # use surface_condition
         color_coeff = WATER_COLOR_COEFFS[surface_condition]
         wave_roughness_coeff = WATER_ROUGHNESS_COEFFS[surface_condition]
 
+    elif surface_condition is None and not (
+        color_coeff is None or wave_roughness_coeff is None
+    ):
+        # use provided color_coeff and wave_roughness_coeff
+        pass
+    else:
+        raise ValueError(
+            "Either a `surface_condition` has to be chosen or"
+            " a combination of `color_coeff` and"
+            " `wave_roughness_coeff`."
+        )
     solar_elevation = np.where(solar_elevation < 0, 0, solar_elevation)
 
     albedo = color_coeff ** (wave_roughness_coeff * sind(solar_elevation) + 1)
+
+    if isinstance(solar_elevation, pd.Series):
+        albedo = pd.Series(albedo, index=solar_elevation.index)
+
     return albedo

From 2fce253adcbac4893dc326469f5aad7edfbb5dbd Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com>
Date: Tue, 11 Jun 2024 17:11:40 +0200
Subject: [PATCH 23/30] Update pvlib/albedo.py

Co-authored-by: Echedey Luis <80125792+echedey-ls@users.noreply.github.com>
---
 pvlib/albedo.py | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index a4983e2127..9e3c8c5008 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -44,12 +44,12 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
         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'.
+        * ``'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'``
 
     color_coeff : float, optional
         Water color coefficient. [-]

From 98a50061beb0d2d7d6757c0bdd2f06da6784b9bc Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Tue, 11 Jun 2024 17:29:09 +0200
Subject: [PATCH 24/30] Update test_albedo.py

---
 pvlib/tests/test_albedo.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/pvlib/tests/test_albedo.py b/pvlib/tests/test_albedo.py
index bef2841ed6..80cd7f0538 100644
--- a/pvlib/tests/test_albedo.py
+++ b/pvlib/tests/test_albedo.py
@@ -51,6 +51,19 @@ def test_albedo_water_series():
     assert_series_equal(expected, result, atol=1e-5)
 
 
+def test_albedo_water_series_mix_with_array():
+    times = pd.date_range(start="2015-01-01 00:00", end="2015-01-01 06:00",
+                             freq="6h")
+    solar_elevs = pd.Series([45, 60], index=times)
+    color_coeffs = 0.13
+    roughness_coeffs = 0.29
+    result = albedo.inland_water_dvoracek(solar_elevation=solar_elevs,
+                                          color_coeff=color_coeffs,
+                                          wave_roughness_coeff=roughness_coeffs)   # noqa: E501
+    expected = pd.Series([0.08555, 0.07787], index=times)
+    assert_series_equal(expected, result, atol=1e-5)
+
+
 def test_albedo_water_invalid():
     with pytest.raises(ValueError):  # no surface info given
         albedo.inland_water_dvoracek(solar_elevation=45)

From 773802084612aa62f757b7f38baf142d61d3fd62 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Tue, 11 Jun 2024 17:31:23 +0200
Subject: [PATCH 25/30] fixed linter

---
 pvlib/albedo.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index 9e3c8c5008..f602f604ab 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -123,8 +123,8 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
         raise ValueError(
             "Either a `surface_condition` has to be chosen or"
             " a combination of `color_coeff` and"
-            " `wave_roughness_coeff`."
-        )
+            " `wave_roughness_coeff`.")
+
     solar_elevation = np.where(solar_elevation < 0, 0, solar_elevation)
 
     albedo = color_coeff ** (wave_roughness_coeff * sind(solar_elevation) + 1)

From 7d55e30627c44b1c628463f478f9e6bed1088db7 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Tue, 11 Jun 2024 17:34:25 +0200
Subject: [PATCH 26/30] now I actually fixed linter

---
 pvlib/tests/test_albedo.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pvlib/tests/test_albedo.py b/pvlib/tests/test_albedo.py
index 80cd7f0538..89ec6d24bc 100644
--- a/pvlib/tests/test_albedo.py
+++ b/pvlib/tests/test_albedo.py
@@ -53,7 +53,7 @@ def test_albedo_water_series():
 
 def test_albedo_water_series_mix_with_array():
     times = pd.date_range(start="2015-01-01 00:00", end="2015-01-01 06:00",
-                             freq="6h")
+                          freq="6h")
     solar_elevs = pd.Series([45, 60], index=times)
     color_coeffs = 0.13
     roughness_coeffs = 0.29

From 4bfc6d12a590f06d720dafeee711279376c8adba Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Tue, 11 Jun 2024 17:58:50 +0200
Subject: [PATCH 27/30] Reviewers' comments vol. 4

---
 pvlib/albedo.py            |  6 ++++--
 pvlib/tests/test_albedo.py | 14 ++++++++++----
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index f602f604ab..56e42a3cc7 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -125,9 +125,11 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
             " a combination of `color_coeff` and"
             " `wave_roughness_coeff`.")
 
-    solar_elevation = np.where(solar_elevation < 0, 0, solar_elevation)
+    solar_elevation_positive = np.where(solar_elevation < 0, 0,
+                                        solar_elevation)
 
-    albedo = color_coeff ** (wave_roughness_coeff * sind(solar_elevation) + 1)
+    albedo = color_coeff ** (wave_roughness_coeff *
+                             sind(solar_elevation_positive) + 1)
 
     if isinstance(solar_elevation, pd.Series):
         albedo = pd.Series(albedo, index=solar_elevation.index)
diff --git a/pvlib/tests/test_albedo.py b/pvlib/tests/test_albedo.py
index 89ec6d24bc..08c8d8fcb7 100644
--- a/pvlib/tests/test_albedo.py
+++ b/pvlib/tests/test_albedo.py
@@ -65,14 +65,20 @@ def test_albedo_water_series_mix_with_array():
 
 
 def test_albedo_water_invalid():
-    with pytest.raises(ValueError):  # no surface info given
+    with pytest.raises(ValueError, match='Either a `surface_condition` has to '
+                       'be chosen or a combination of `color_coeff` and'
+                       ' `wave_roughness_coeff`.'):  # no surface info given
         albedo.inland_water_dvoracek(solar_elevation=45)
-    with pytest.raises(KeyError):  # invalid surface type
+    with pytest.raises(KeyError, match='not_a_surface_type'):  # invalid type
         albedo.inland_water_dvoracek(solar_elevation=45,
                                      surface_condition='not_a_surface_type')
-    with pytest.raises(ValueError):  # only one coefficient given
+    with pytest.raises(ValueError, match='Either a `surface_condition` has to '
+                       'be chosen or a combination of `color_coeff` and'
+                       ' `wave_roughness_coeff`.'):  # only one coeff given
         albedo.inland_water_dvoracek(solar_elevation=45,
                                      color_coeff=0.13)
-    with pytest.raises(ValueError):  # only one coefficient given
+    with pytest.raises(ValueError, match='Either a `surface_condition` has to '
+                       'be chosen or a combination of `color_coeff` and'
+                       ' `wave_roughness_coeff`.'):  # only one coeff given
         albedo.inland_water_dvoracek(solar_elevation=45,
                                      wave_roughness_coeff=0.29)

From eaaced0b17af7ae0d006621775a5adb6bfeaf681 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Tue, 11 Jun 2024 18:09:30 +0200
Subject: [PATCH 28/30] renaming tests

---
 pvlib/tests/test_albedo.py | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/pvlib/tests/test_albedo.py b/pvlib/tests/test_albedo.py
index 08c8d8fcb7..5e4c35258a 100644
--- a/pvlib/tests/test_albedo.py
+++ b/pvlib/tests/test_albedo.py
@@ -7,27 +7,27 @@
 from numpy.testing import assert_allclose
 
 
-def test_albedo_water_default():
+def test_inland_water_dvoracek_default():
     result = albedo.inland_water_dvoracek(solar_elevation=90,
                                           color_coeff=0.13,
                                           wave_roughness_coeff=0.29)
     assert_allclose(result, 0.072, 0.001)
 
 
-def test_albedo_water_negative_elevation():
+def test_inland_water_dvoracek_negative_elevation():
     result = albedo.inland_water_dvoracek(solar_elevation=-60,
                                           color_coeff=0.13,
                                           wave_roughness_coeff=0.29)
     assert_allclose(result, 0.13, 0.01)
 
 
-def test_albedo_water_string_surface_condition():
+def test_inland_water_dvoracek_string_surface_condition():
     result = albedo.inland_water_dvoracek(solar_elevation=90,
                                           surface_condition='clear_water_no_waves')   # noqa: E501
     assert_allclose(result, 0.072, 0.001)
 
 
-def test_albedo_water_ndarray():
+def test_inland_water_dvoracek_ndarray():
     solar_elevs = np.array([-50, 0, 20, 60, 90])
     color_coeffs = np.array([0.1, 0.1, 0.2, 0.3, 0.4])
     roughness_coeffs = np.array([0.3, 0.3, 0.8, 1.5, 2])
@@ -38,7 +38,7 @@ def test_albedo_water_ndarray():
     assert_allclose(expected, result, atol=1e-5)
 
 
-def test_albedo_water_series():
+def test_inland_water_dvoracek_series():
     times = pd.date_range(start="2015-01-01 00:00", end="2015-01-02 00:00",
                           freq="6h")
     solar_elevs = pd.Series([-50, 0, 20, 60, 90], index=times)
@@ -51,7 +51,7 @@ def test_albedo_water_series():
     assert_series_equal(expected, result, atol=1e-5)
 
 
-def test_albedo_water_series_mix_with_array():
+def test_inland_water_dvoracek_series_mix_with_array():
     times = pd.date_range(start="2015-01-01 00:00", end="2015-01-01 06:00",
                           freq="6h")
     solar_elevs = pd.Series([45, 60], index=times)
@@ -64,7 +64,7 @@ def test_albedo_water_series_mix_with_array():
     assert_series_equal(expected, result, atol=1e-5)
 
 
-def test_albedo_water_invalid():
+def test_inland_water_dvoracek_invalid():
     with pytest.raises(ValueError, match='Either a `surface_condition` has to '
                        'be chosen or a combination of `color_coeff` and'
                        ' `wave_roughness_coeff`.'):  # no surface info given

From 7776c337429421873314b5c2fbc3e371e0ef74ea Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com>
Date: Tue, 11 Jun 2024 20:39:48 +0200
Subject: [PATCH 29/30] Update pvlib/albedo.py

Co-authored-by: Echedey Luis <80125792+echedey-ls@users.noreply.github.com>
---
 pvlib/albedo.py | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index 56e42a3cc7..471d809198 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -62,6 +62,16 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
     albedo : numeric
         Albedo for inland water bodies. [-]
 
+    Raises
+    ------
+    ValueError
+        If neither of ``surface_condition`` nor the pair ``color_coeff`` and ``wave_roughness_coeff`` are given.
+        If ``surface_condition`` and any of ``color_coeff`` or ``wave_roughness_coeff`` are given.
+        These parameters are mutually exclusive.
+
+    KeyError
+        If ``surface_condition`` is invalid.
+
     Notes
     -----
     The equation for calculating the albedo :math:`\rho` is given by

From 0645463e5e76df36463719e7357e46350b6ee6e9 Mon Sep 17 00:00:00 2001
From: Ioannis Sifnaios <john_sif@hotmail.com>
Date: Tue, 11 Jun 2024 20:44:45 +0200
Subject: [PATCH 30/30] Update albedo.py

---
 pvlib/albedo.py | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/pvlib/albedo.py b/pvlib/albedo.py
index 471d809198..98b920dddb 100644
--- a/pvlib/albedo.py
+++ b/pvlib/albedo.py
@@ -65,9 +65,11 @@ def inland_water_dvoracek(solar_elevation, surface_condition=None,
     Raises
     ------
     ValueError
-        If neither of ``surface_condition`` nor the pair ``color_coeff`` and ``wave_roughness_coeff`` are given.
-        If ``surface_condition`` and any of ``color_coeff`` or ``wave_roughness_coeff`` are given.
-        These parameters are mutually exclusive.
+        If neither of ``surface_condition`` nor a combination of
+        ``color_coeff`` and ``wave_roughness_coeff`` are given.
+        If ``surface_condition`` and any of ``color_coeff`` or
+        ``wave_roughness_coeff`` are given. These parameters are
+        mutually exclusive.
 
     KeyError
         If ``surface_condition`` is invalid.