diff --git a/docs/sphinx/source/whatsnew/v0.15.2.rst b/docs/sphinx/source/whatsnew/v0.15.2.rst index d0fd0f5b25..0f32b734ef 100644 --- a/docs/sphinx/source/whatsnew/v0.15.2.rst +++ b/docs/sphinx/source/whatsnew/v0.15.2.rst @@ -22,6 +22,9 @@ Enhancements Documentation ~~~~~~~~~~~~~ +* Clarified that :py:func:`pvlib.soiling.hsu` has an implicit minimum + soiling ratio of approximately 0.6563 due to the mathematical form + of the model. (:issue:`2534`, :pull:`2743`) Testing @@ -42,4 +45,4 @@ Maintenance Contributors ~~~~~~~~~~~~ - +* :ghuser:`Omesh37` diff --git a/pvlib/soiling.py b/pvlib/soiling.py index 6f81d76f0e..b7582dbedf 100644 --- a/pvlib/soiling.py +++ b/pvlib/soiling.py @@ -16,9 +16,11 @@ def hsu(rainfall, cleaning_threshold, surface_tilt, pm2_5, pm10, Calculates soiling ratio given particulate and rain data using the Fixed Velocity model from Humboldt State University (HSU). - The HSU soiling model [1]_ returns the soiling ratio, a value between zero - and one which is equivalent to (1 - transmission loss). Therefore a soiling - ratio of 1.0 is equivalent to zero transmission loss. + The HSU soiling model [1]_ returns the soiling ratio, a value between + zero and one which is equivalent to (1 - transmission loss). + Therefore a soiling ratio of 1.0 is equivalent to zero transmission loss. + Due to the mathematical form of the HSU model, the soiling ratio has a + minimum of approximately 0.6563. See ``Notes`` for details. Parameters ---------- @@ -54,6 +56,17 @@ def hsu(rainfall, cleaning_threshold, surface_tilt, pm2_5, pm10, soiling_ratio : Series Values between 0 and 1. Equal to 1 - transmission loss. + Notes + ------- + Due to the mathematical form of the HSU model + (``SR = 1 - 0.3437 * erf(0.17 * ω^0.8473)``), + the soiling ratio has a minimum value of approximately 0.6563 + (i.e., maximum transmission loss of ~34.37%), regardless of + the accumulated particulate mass. The HSU model is developed + (validated) for accumulated mass densities up to 10 g/m², + corresponding to a soiling ratio of approximately 0.6875. + See [1]_ for details. + References ----------- .. [1] M. Coello and L. Boyle, "Simple Model For Predicting Time Series