Correct usage of xtol in ghi_from_poa_driesse_2023

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

@@ -14,6 +14,8 @@ Bug fixes
 ~~~~~~~~~
 * :py:class:`~pvlib.modelchain.ModelChain` now raises a more useful error when
   ``temperature_model_parameters`` are specified on the passed ``system`` instead of on its ``arrays``. (:issue:`1759`).
+* :py:func:`pvlib.irradiance.ghi_from_poa_driesse_2023` now correctly makes use
+  of the ``xtol`` argument. Previously, it was ignored. (:issue:`1970`, :pull:`1971`)
 
 Testing
 ~~~~~~~

pvlib/irradiance.py

@@ -1513,11 +1513,15 @@ def poa_error(ghi):
                         full_output=True,
                         disp=False,
                         )
-    except ValueError:
-        # this occurs when poa_error has the same sign at both end points
-        ghi = np.nan
-        conv = False
-        niter = -1
+    except ValueError as e:
+        if "f(a) and f(b) must have different signs" in e.args:
+            # this occurs when poa_error has the same sign at both end points
+            ghi = np.nan
+            conv = False
+            niter = -1
+        else:
+            # propagate other ValueError's, like a non-positive xtol
+            raise e
     else:
         ghi = result[0]
         conv = result[1].converged
@@ -1557,8 +1561,8 @@ def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
     albedo : numeric, default 0.25
         Ground surface albedo. [unitless]
     xtol : numeric, default 0.01
-        Convergence criterion.  The estimated GHI will be within xtol of the
-        true value. [W/m^2]
+        Convergence criterion. The estimated GHI will be within xtol of the
+        true value. Must be positive. [W/m^2]
     full_output : boolean, default False
         If full_output is False, only ghi is returned, otherwise the return
         value is (ghi, converged, niter). (see Returns section for details).
@@ -1599,7 +1603,7 @@ def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
                                           solar_zenith, solar_azimuth,
                                           poa_global,
                                           dni_extra, airmass, albedo,
-                                          xtol=0.01)
+                                          xtol=xtol)
 
     if isinstance(poa_global, pd.Series):
         ghi = pd.Series(ghi, poa_global.index)

pvlib/tests/test_irradiance.py

@@ -825,6 +825,14 @@ def test_ghi_from_poa_driesse():
     expected = [0, -1, 0]
     assert_allclose(expected, niter)
 
+    # test xtol propagation by producing an exception
+    poa_global = pd.Series([20, 300, 1000], index=times)
+    xtol = -3.14159  # negative value raises exception in scipy.optimize.bisect
+    with pytest.raises(ValueError, match=r"xtol too small \(%g <= 0\)" % xtol):
+        output = irradiance.ghi_from_poa_driesse_2023(
+            surface_tilt, surface_azimuth, zenith, azimuth,
+            poa_global, dni_extra=1366.1, xtol=xtol)
+
 
 def test_gti_dirint():
     times = pd.DatetimeIndex(