Merge remote-tracking branch 'upstream/main' into pvsystem_racking

Author: RDaxini

.github/workflows/top-ranked-issues.yml

@@ -0,0 +1,34 @@
+name: Update Top Ranked Issues
+
+on:
+  # For testing purposes (can be removed later)
+  pull_request:  
+  schedule:
+    # # Runs every day at 3:00 AM UTC
+    # - cron: '0 3 * * *'
+    - cron: '*/10 * * * *'
+
+jobs:
+  run-script:
+    runs-on: ubuntu-latest
+
+    env:
+      GITHUB_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v4  # This ensures the repository code is available
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install PyGithub
+
+      - name: Run update_top_ranking_issues.py
+        run: |
+          python ./scripts/update_top_ranking_issues.py

README.md

@@ -81,7 +81,7 @@ Contributing
 ============
 
 We need your help to make pvlib-python a great tool!
-Please see the [Contributing page](http://pvlib-python.readthedocs.io/en/stable/contributing.html) for more on how you can contribute.
+Please see the [Contributing page](https://pvlib-python.readthedocs.io/en/stable/contributing/index.html) for more on how you can contribute.
 The long-term success of pvlib-python requires substantial community support.
 
 

docs/sphinx/source/contributing/testing.rst

@@ -1,7 +1,7 @@
 .. _testing:
 
-Testing
-=======
+Testing and benchmarking
+========================
 
 .. _overview:
 

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

@@ -22,7 +22,8 @@ Documentation
   racking model option, and various formatting edits for clarity.
   (:issue:`1942`, :pull:`2232`)
   :py:func:`~pvlib.pvsystem.dc_ohmic_losses` for clarity. (:issue:`1601`, :pull:`2229`)
-
+* Updated :py:func:`~pvlib.irradiance.reindl` to include definitions of terms
+  and a new "notes" section (:issue:`2183`, :pull:`2193`)
 
 Testing
 ~~~~~~~
@@ -32,8 +33,17 @@ Requirements
 ~~~~~~~~~~~~
 
 
+Maintenance
+~~~~~~~~~~~
+* Added a decorator to deprecate renamed keyword arguments in functions,
+  :py:func:`pvlib._deprecation.renamed_kwarg_warning`. (:pull:`2237`)
+
+
 Contributors
 ~~~~~~~~~~~~
 * Cliff Hansen (:ghuser:`cwhanse`)
 * Rajiv Daxini (:ghuser:`RDaxini`)
 
+* Mark Mikofski (:ghuser:`mikofski`)
+* matsuobasho (:ghuser:`matsuobasho`)
+* Echedey Luis (:ghuser:`echedey-ls`)

pvlib/_deprecation.py

@@ -316,3 +316,76 @@ def wrapper(*args, **kwargs):
         return finalize(wrapper, new_doc)
 
     return deprecate
+
+
+def renamed_kwarg_warning(since, old_param_name, new_param_name, removal=""):
+    """
+    Decorator to mark a possible keyword argument as deprecated and replaced
+    with other name.
+
+    Raises a warning when the deprecated argument is used, and replaces the
+    call with the new argument name. Does not modify the function signature.
+
+    .. warning::
+        Ensure ``removal`` date with a ``fail_on_pvlib_version`` decorator in
+        the test suite.
+
+    .. note::
+        Not compatible with positional-only arguments.
+
+    .. note::
+        Documentation for the function may updated to reflect the new parameter
+        name; it is suggested to add a |.. versionchanged::| directive.
+
+    Parameters
+    ----------
+    since : str
+        The release at which this API became deprecated.
+    old_param_name : str
+        The name of the deprecated parameter.
+    new_param_name : str
+        The name of the new parameter.
+    removal : str, optional
+        The expected removal version, in order to compose the Warning message.
+
+    Examples
+    --------
+    >>> @renamed_kwarg_warning("1.4.0", "old_name", "new_name", "1.6.0")
+    >>> def some_function(new_name=None):
+    >>>     pass
+    >>> some_function(old_name=1)
+    Parameter 'old_name' has been renamed since 1.4.0. and
+    will be removed in 1.6.0. Please use 'new_name' instead.
+
+    >>> @renamed_kwarg_warning("1.4.0", "old_name", "new_name")
+    >>> def some_function(new_name=None):
+    >>>     pass
+    >>> some_function(old_name=1)
+    Parameter 'old_name' has been renamed since 1.4.0. and
+    will be removed soon. Please use 'new_name' instead.
+    """
+
+    def deprecate(func, old=old_param_name, new=new_param_name, since=since):
+        def wrapper(*args, **kwargs):
+            if old in kwargs:
+                if new in kwargs:
+                    raise ValueError(
+                        f"{func.__name__} received both '{old}' and '{new}', "
+                        "which are mutually exclusive since they refer to the "
+                        f"same parameter. Please remove deprecated '{old}'."
+                    )
+                warnings.warn(
+                    f"Parameter '{old}' has been renamed since {since}. "
+                    f"and will be removed "
+                    + (f"in {removal}" if removal else "soon")
+                    + f". Please use '{new}' instead.",
+                    _projectWarning,
+                    stacklevel=2,
+                )
+                kwargs[new] = kwargs.pop(old)
+            return func(*args, **kwargs)
+
+        wrapper = functools.wraps(func)(wrapper)
+        return wrapper
+
+    return deprecate

pvlib/data/variables_style_rules.csv

@@ -11,7 +11,7 @@ ghi;global horizontal irradiance
 ghi_extra;horizontal irradiance at top of atmosphere (extraterrestrial)
 gri;ground-reflected irradiance
 ape;average photon energy
-aoi;angle of incidence between :math:`90\deg` and :math:`90\deg`
+aoi;angle of incidence. Angle between the surface normal vector and the vector pointing towards the sun's center
 aoi_projection;cos(aoi)
 airmass;airmass
 airmass_relative;relative airmass

pvlib/iam.py

@@ -269,8 +269,8 @@ def martin_ruiz(aoi, a_r=0.16):
 
     which is presented as :math:`AL(\alpha) = 1 - IAM` in equation 4 of [1]_,
     with :math:`\alpha` representing the angle of incidence AOI. Thus IAM = 1
-    at AOI = 0, and IAM = 0 at AOI = 90.  This equation is only valid for
-    -90 <= aoi <= 90, therefore `iam` is constrained to 0.0 outside this
+    at AOI = 0°, and IAM = 0 at AOI = 90°.  This equation is only valid for
+    0° <= aoi <= 90°, therefore `iam` is constrained to 0.0 outside this
     interval.
 
     References
@@ -891,8 +891,8 @@ def schlick_diffuse(surface_tilt):
     implements only the integrated Schlick approximation.
 
     Note also that the output of this function (which is an exact integration)
-    can be compared with the output of :py:func:`marion_diffuse` which numerically
-    integrates the Schlick approximation:
+    can be compared with the output of :py:func:`marion_diffuse` which
+    numerically integrates the Schlick approximation:
 
     .. code::
 

pvlib/irradiance.py

@@ -871,19 +871,14 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 def reindl(surface_tilt, surface_azimuth, dhi, dni, ghi, dni_extra,
            solar_zenith, solar_azimuth):
     r'''
-    Determine diffuse irradiance from the sky on a tilted surface using
-    Reindl's 1990 model
-
-    .. math::
+    Determine the diffuse irradiance from the sky on a tilted surface using
+    the Reindl (1990) model.
 
-       I_{d} = DHI \left(A R_b + (1 - A) \left(\frac{1 + \cos\beta}{2}\right)
-       \left(1 + \sqrt{\frac{I_{hb}}{I_h}} \sin^3(\beta/2)\right) \right)
-
-    Reindl's 1990 model determines the diffuse irradiance from the sky
-    (ground reflected irradiance is not included in this algorithm) on a
-    tilted surface using the surface tilt angle, surface azimuth angle,
+    The Reindl (1990) model [1]_ [2]_ determines the diffuse irradiance from
+    the sky on
+    a tilted surface using the surface tilt angle, surface azimuth angle,
     diffuse horizontal irradiance, direct normal irradiance, global
-    horizontal irradiance, extraterrestrial irradiance, sun zenith
+    horizontal irradiance, extraterrestrial normal irradiance, sun zenith
     angle, and sun azimuth angle.
 
     Parameters
@@ -905,7 +900,7 @@ def reindl(surface_tilt, surface_azimuth, dhi, dni, ghi, dni_extra,
         direct normal irradiance. [Wm⁻²]
 
     ghi: numeric
-        Global irradiance. [Wm⁻²]
+        Global horizontal irradiance. [Wm⁻²]
 
     dni_extra : numeric
         Extraterrestrial normal irradiance. [Wm⁻²]
@@ -925,23 +920,41 @@ def reindl(surface_tilt, surface_azimuth, dhi, dni, ghi, dni_extra,
 
     Notes
     -----
-    The poa_sky_diffuse calculation is generated from the Loutzenhiser et al.
-    (2007) paper, equation 8. Note that I have removed the beam and ground
-    reflectance portion of the equation and this generates ONLY the diffuse
-    radiation from the sky and circumsolar, so the form of the equation
-    varies slightly from equation 8.
+    The Reindl (1990) model  for the sky diffuse irradiance,
+    :math:`I_d`, is as follows:
+
+    .. math::
+
+       I_{d} = DHI \left(A \cdot R_b + (1 - A)
+                         \left(\frac{1 + \cos\beta}{2}\right)
+       \left(1 + \sqrt{\frac{BHI}{GHI}} \sin^3(\beta/2)\right) \right).
+
+    :math:`DHI`, :math:`BHI`, and :math:`GHI` are the diffuse horizontal, beam
+    (direct) horizontal and global horizontal irradiances, respectively.
+    :math:`A` is the anisotropy index, which is the ratio of the direct normal
+    irradiance to the direct extraterrestrial irradiation, :math:`R_b` is the
+    projection ratio, which is defined as the ratio of the cosine of the angle
+    of incidence (AOI) to the cosine of the zenith angle, and :math:`\beta`
+    is the tilt angle of the array.
+
+    Implementation is based on Loutzenhiser et al.
+    (2007) [3]_, Equation 8. The beam and ground reflectance portion of the
+    equation have been removed, therefore the model described here generates
+    ONLY the diffuse radiation from the sky and circumsolar, so the form of the
+    equation varies slightly from Equation 8 in [3]_.
 
     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] Reindl, D.T., Beckmann, W.A., Duffie, J.A., 1990a. Diffuse
+    .. [1] Reindl, D. T., Beckmann, W. A., Duffie, J. A., 1990a. Diffuse
        fraction correlations. Solar Energy 45(1), 1-7.
-
-    .. [3] Reindl, D.T., Beckmann, W.A., Duffie, J.A., 1990b. Evaluation of
+       :doi:`10.1016/0038-092X(90)90060-P`
+    .. [2] Reindl, D. T., Beckmann, W. A., Duffie, J. A., 1990b. Evaluation of
        hourly tilted surface radiation models. Solar Energy 45(1), 9-17.
+       :doi:`10.1016/0038-092X(90)90061-G`
+    .. [3] Loutzenhiser P. G. et. al., 2007. Empirical validation of models to
+       compute solar irradiance on inclined surfaces for building energy
+       simulation. Solar Energy 81(2), 254-267
+       :doi:`10.1016/j.solener.2006.03.009`
     '''
 
     cos_tt = aoi_projection(surface_tilt, surface_azimuth,

pvlib/tests/test__deprecation.py

@@ -0,0 +1,97 @@
+"""
+Test the _deprecation module.
+"""
+
+import pytest
+
+from pvlib import _deprecation
+from .conftest import fail_on_pvlib_version
+
+import warnings
+
+
+@pytest.mark.xfail(strict=True,
+                   reason='fail_on_pvlib_version should cause test to fail')
+@fail_on_pvlib_version('0.0')
+def test_fail_on_pvlib_version():
+    pass  # pragma: no cover
+
+
+@fail_on_pvlib_version('100000.0')
+def test_fail_on_pvlib_version_pass():
+    pass
+
+
+@pytest.mark.xfail(strict=True, reason='ensure that the test is called')
+@fail_on_pvlib_version('100000.0')
+def test_fail_on_pvlib_version_fail_in_test():
+    raise Exception
+
+
+# set up to test using fixtures with function decorated with
+# conftest.fail_on_pvlib_version
+@pytest.fixture
+def some_data():
+    return "some data"
+
+
+def alt_func(*args):
+    return args
+
+
+@pytest.fixture
+def deprec_func():
+    return _deprecation.deprecated(
+        "350.8", alternative="alt_func", name="deprec_func", removal="350.9"
+    )(alt_func)
+
+
+@fail_on_pvlib_version('350.9')
+def test_use_fixture_with_decorator(some_data, deprec_func):
+    # test that the correct data is returned by the some_data fixture
+    assert some_data == "some data"
+    with pytest.warns(_deprecation.pvlibDeprecationWarning):
+        # test for custom deprecation warning provided by pvlib
+        deprec_func(some_data)
+
+
+@pytest.fixture
+def renamed_kwarg_func():
+    """Returns a function decorated by renamed_kwarg_warning.
+    This function is called 'func' and has a docstring equal to 'docstring'.
+    """
+
+    @_deprecation.renamed_kwarg_warning(
+        "0.1.0", "old_kwarg", "new_kwarg", "0.2.0"
+    )
+    def func(new_kwarg):
+        """docstring"""
+        return new_kwarg
+
+    return func
+
+
+def test_renamed_kwarg_warning(renamed_kwarg_func):
+    # assert decorated function name and docstring are unchanged
+    assert renamed_kwarg_func.__name__ == "func"
+    assert renamed_kwarg_func.__doc__ == "docstring"
+
+    # assert no warning is raised when using the new kwarg
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        assert renamed_kwarg_func(new_kwarg=1) == 1  # as keyword argument
+        assert renamed_kwarg_func(1) == 1  # as positional argument
+
+    # assert a warning is raised when using the old kwarg
+    with pytest.warns(Warning, match="Parameter 'old_kwarg' has been renamed"):
+        assert renamed_kwarg_func(old_kwarg=1) == 1
+
+    # assert an error is raised when using both the old and new kwarg
+    with pytest.raises(ValueError, match="they refer to the same parameter."):
+        renamed_kwarg_func(old_kwarg=1, new_kwarg=2)
+
+    # assert when not providing any of them
+    with pytest.raises(
+        TypeError, match="missing 1 required positional argument"
+    ):
+        renamed_kwarg_func()