Rename tilt to surface_tilt in soiling.hsu (#1738)

* tilt -> surface_tilt

* whatsnew

* document surface_tilt as numeric, not float

Author: kandersolar

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

@@ -5,6 +5,12 @@ v0.9.6 (Anticipated June 2023)
 ------------------------------
 
 
+Breaking Changes
+~~~~~~~~~~~~~~~~
+* For consistency with the rest of pvlib, the ``tilt`` parameter is renamed
+  to ``surface_tilt`` in :py:func:`pvlib.soiling.hsu`. (:issue:`1717`, :pull:`1738`)
+  
+
 Deprecations
 ~~~~~~~~~~~~
 

pvlib/soiling.py

@@ -10,7 +10,7 @@
 from pvlib.tools import cosd
 
 
-def hsu(rainfall, cleaning_threshold, tilt, pm2_5, pm10,
+def hsu(rainfall, cleaning_threshold, surface_tilt, pm2_5, pm10,
         depo_veloc=None, rain_accum_period=pd.Timedelta('1h')):
     """
     Calculates soiling ratio given particulate and rain data using the
@@ -30,7 +30,7 @@ def hsu(rainfall, cleaning_threshold, tilt, pm2_5, pm10,
         Amount of rain in an accumulation period needed to clean the PV
         modules. [mm]
 
-    tilt : float
+    surface_tilt : numeric
         Tilt of the PV panels from horizontal. [degree]
 
     pm2_5 : numeric
@@ -83,7 +83,7 @@ def hsu(rainfall, cleaning_threshold, tilt, pm2_5, pm10,
     horiz_mass_rate = (
         pm2_5 * depo_veloc['2_5'] + np.maximum(pm10 - pm2_5, 0.)
         * depo_veloc['10']) * dt_sec
-    tilted_mass_rate = horiz_mass_rate * cosd(tilt)  # assuming no rain
+    tilted_mass_rate = horiz_mass_rate * cosd(surface_tilt)  # assuming no rain
 
     # tms -> tilt_mass_rate
     tms_cumsum = np.cumsum(tilted_mass_rate * np.ones(rainfall.shape))

pvlib/tests/test_soiling.py

@@ -92,7 +92,7 @@ def test_hsu_no_cleaning(rainfall_input, expected_output):
     tilt = 0.
     expected_no_cleaning = expected_output
 
-    result = hsu(rainfall=rainfall, cleaning_threshold=10., tilt=tilt,
+    result = hsu(rainfall=rainfall, cleaning_threshold=10., surface_tilt=tilt,
                  pm2_5=pm2_5, pm10=pm10, depo_veloc=depo_veloc,
                  rain_accum_period=pd.Timedelta('1h'))
     assert_series_equal(result, expected_no_cleaning)
@@ -108,7 +108,7 @@ def test_hsu(rainfall_input, expected_output_2):
     tilt = 0.
 
     # three cleaning events at 4:00-6:00, 8:00-11:00, and 17:00-20:00
-    result = hsu(rainfall=rainfall, cleaning_threshold=0.5, tilt=tilt,
+    result = hsu(rainfall=rainfall, cleaning_threshold=0.5, surface_tilt=tilt,
                  pm2_5=pm2_5, pm10=pm10, depo_veloc=depo_veloc,
                  rain_accum_period=pd.Timedelta('3h'))
 
@@ -120,8 +120,8 @@ def test_hsu_defaults(rainfall_input, expected_output_1):
     Test Soiling HSU function with default deposition velocity and default rain
     accumulation period.
     """
-    result = hsu(rainfall=rainfall_input, cleaning_threshold=0.5, tilt=0.0,
-                 pm2_5=1.0e-2, pm10=2.0e-2)
+    result = hsu(rainfall=rainfall_input, cleaning_threshold=0.5,
+                 surface_tilt=0.0, pm2_5=1.0e-2, pm10=2.0e-2)
     assert np.allclose(result.values, expected_output_1)
 
 
@@ -138,7 +138,7 @@ def test_hsu_variable_time_intervals(rainfall_input, expected_output_3):
     rain['new_time'] = rain.index + rain['mins_added']
     rain_var_times = rain.set_index('new_time').iloc[:, 0]
     result = hsu(
-        rainfall=rain_var_times, cleaning_threshold=0.5, tilt=50.0,
+        rainfall=rain_var_times, cleaning_threshold=0.5, surface_tilt=50.0,
         pm2_5=1, pm10=2, depo_veloc=depo_veloc,
         rain_accum_period=pd.Timedelta('2h'))
     assert np.allclose(result, expected_output_3)