From d1aecc4b0ecb4f05c9627d6f36a9c2b2c2bdb3eb Mon Sep 17 00:00:00 2001 From: Omesh37 Date: Sun, 26 Apr 2026 10:32:12 +0530 Subject: [PATCH 1/9] 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/9] 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 From ab05de211d89128536a3b0d187f9411dd7d2667d Mon Sep 17 00:00:00 2001 From: OMESH CHANDURE Date: Mon, 27 Apr 2026 21:57:46 +0530 Subject: [PATCH 3/9] Update pvlib/soiling.py Co-authored-by: Cliff Hansen --- pvlib/soiling.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pvlib/soiling.py b/pvlib/soiling.py index b99e3c18a1..21de36c5cb 100644 --- a/pvlib/soiling.py +++ b/pvlib/soiling.py @@ -19,8 +19,8 @@ def hsu(rainfall, cleaning_threshold, surface_tilt, pm2_5, pm10, 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. + Due to the mathematical form of the HSU model, the soiling ratio has a + minimum of approximately 0.6563. See ``Returns`` for details. Parameters ---------- From a85ae48fc6cb39822a989c174ee63c6380743f49 Mon Sep 17 00:00:00 2001 From: Omesh37 Date: Mon, 27 Apr 2026 22:02:26 +0530 Subject: [PATCH 4/9] DOC: address review comments - move details to Notes section --- pvlib/soiling.py | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/pvlib/soiling.py b/pvlib/soiling.py index b99e3c18a1..aef6dc6d59 100644 --- a/pvlib/soiling.py +++ b/pvlib/soiling.py @@ -55,14 +55,17 @@ def hsu(rainfall, cleaning_threshold, surface_tilt, pm2_5, pm10, ------- 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. + +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 ----------- From dceec7c996a53815e785b0b2c8598d454a46adf2 Mon Sep 17 00:00:00 2001 From: Omesh37 Date: Mon, 27 Apr 2026 22:05:07 +0530 Subject: [PATCH 5/9] DOC: address review comments - move details to Notes section --- pvlib/soiling.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pvlib/soiling.py b/pvlib/soiling.py index aef6dc6d59..ac1adb77da 100644 --- a/pvlib/soiling.py +++ b/pvlib/soiling.py @@ -19,8 +19,8 @@ def hsu(rainfall, cleaning_threshold, surface_tilt, pm2_5, pm10, 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. + Due to the mathematical form of the HSU model, the soiling ratio has a + minimum of approximately 0.6563. See ``Returns`` for details. Parameters ---------- From 98cb49ed5e06153617ea539e12dd2439a2565fe8 Mon Sep 17 00:00:00 2001 From: OMESH CHANDURE Date: Mon, 27 Apr 2026 23:01:05 +0530 Subject: [PATCH 6/9] Update pvlib/soiling.py Co-authored-by: Cliff Hansen --- pvlib/soiling.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pvlib/soiling.py b/pvlib/soiling.py index ac1adb77da..78ade86726 100644 --- a/pvlib/soiling.py +++ b/pvlib/soiling.py @@ -56,7 +56,7 @@ def hsu(rainfall, cleaning_threshold, surface_tilt, pm2_5, pm10, soiling_ratio : Series Values between 0 and 1. Equal to 1 - transmission loss. -Notes + Notes ------- Due to the mathematical form of the HSU model (``SR = 1 - 0.3437 * erf(0.17 * ω^0.8473)``), From fc3986129250baae210a44ea7a204073c5a2f293 Mon Sep 17 00:00:00 2001 From: OMESH CHANDURE Date: Mon, 27 Apr 2026 23:01:13 +0530 Subject: [PATCH 7/9] Update docs/sphinx/source/whatsnew/v0.15.2.rst Co-authored-by: Cliff Hansen --- 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 5ccef70c87..0f32b734ef 100644 --- a/docs/sphinx/source/whatsnew/v0.15.2.rst +++ b/docs/sphinx/source/whatsnew/v0.15.2.rst @@ -45,4 +45,4 @@ Maintenance Contributors ~~~~~~~~~~~~ -Omesh37 +* :ghuser:`Omesh37` From bff0813e5fcc15430e9b3262dab47651f5d58228 Mon Sep 17 00:00:00 2001 From: Omesh37 Date: Mon, 27 Apr 2026 23:04:07 +0530 Subject: [PATCH 8/9] DOC: Corrected the indentation --- pvlib/soiling.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pvlib/soiling.py b/pvlib/soiling.py index ac1adb77da..8de60c25bc 100644 --- a/pvlib/soiling.py +++ b/pvlib/soiling.py @@ -51,12 +51,12 @@ 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. -Notes + Notes ------- Due to the mathematical form of the HSU model (``SR = 1 - 0.3437 * erf(0.17 * ω^0.8473)``), From 417004181e59179c602e06385b6f81b066711785 Mon Sep 17 00:00:00 2001 From: OMESH CHANDURE Date: Tue, 28 Apr 2026 08:15:53 +0530 Subject: [PATCH 9/9] Update pvlib/soiling.py Co-authored-by: Cliff Hansen --- pvlib/soiling.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pvlib/soiling.py b/pvlib/soiling.py index 8de60c25bc..b7582dbedf 100644 --- a/pvlib/soiling.py +++ b/pvlib/soiling.py @@ -20,7 +20,7 @@ def hsu(rainfall, cleaning_threshold, surface_tilt, pm2_5, pm10, 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 ``Returns`` for details. + minimum of approximately 0.6563. See ``Notes`` for details. Parameters ----------