From d1aecc4b0ecb4f05c9627d6f36a9c2b2c2bdb3eb Mon Sep 17 00:00:00 2001 From: Omesh37 Date: Sun, 26 Apr 2026 10:32:12 +0530 Subject: [PATCH 1/2] DOC: clarify hsu soiling ratio minimum value in docstring --- docs/sphinx/source/whatsnew/v0.15.2.rst | 5 ++++- pvlib/soiling.py | 18 ++++++++++++++---- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/sphinx/source/whatsnew/v0.15.2.rst b/docs/sphinx/source/whatsnew/v0.15.2.rst index d0fd0f5b25..5b6c010a01 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:`XXXX`) Testing @@ -42,4 +45,4 @@ Maintenance Contributors ~~~~~~~~~~~~ - +Omesh37 diff --git a/pvlib/soiling.py b/pvlib/soiling.py index 6f81d76f0e..b99e3c18a1 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 model, the soiling ratio has an + implicit minimum of approximately 0.6563. See ``Returns`` for details. Parameters ---------- @@ -49,10 +51,18 @@ def hsu(rainfall, cleaning_threshold, surface_tilt, pm2_5, pm10, It is recommended that `rain_accum_period` be between 1 hour and 24 hours. - Returns +Returns ------- soiling_ratio : Series Values between 0 and 1. Equal to 1 - transmission loss. + Due to the mathematical form of the model + (``SR = 1 - 0.3437 * erf(0.17 * ω^0.8473)``), + the soiling ratio has an implicit minimum value of approximately + 0.6563 (i.e., maximum transmission loss of ~34.37%), regardless + of the accumulated particulate mass. Note that the valid range + of the underlying equation is further limited to accumulated + mass densities up to 10 g/m², corresponding to a soiling ratio + of approximately 0.6875. See [1]_ and [2]_ for details. References ----------- From ff9945980e21db014ed4d6c14e8080b2d4a51d79 Mon Sep 17 00:00:00 2001 From: Omesh37 Date: Sun, 26 Apr 2026 14:34:07 +0530 Subject: [PATCH 2/2] DOC: add PR number to whatsnew --- docs/sphinx/source/whatsnew/v0.15.2.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/source/whatsnew/v0.15.2.rst b/docs/sphinx/source/whatsnew/v0.15.2.rst index 5b6c010a01..5ccef70c87 100644 --- a/docs/sphinx/source/whatsnew/v0.15.2.rst +++ b/docs/sphinx/source/whatsnew/v0.15.2.rst @@ -24,7 +24,7 @@ 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:`XXXX`) + of the model. (:issue:`2534`, :pull:`2743`) Testing