Merge remote-tracking branch 'upstream/main' into prtemplate

Author: RDaxini

docs/sphinx/source/reference/location.rst

@@ -16,6 +16,7 @@ Classes
    :toctree: generated/
 
    location.Location
+
 A :py:class:`~pvlib.location.Location` object may be created from the
 metadata returned by these file types:
 

docs/sphinx/source/whatsnew.rst

@@ -6,7 +6,7 @@ What's New
 
 These are new features and improvements of note in each release.
 
-.. include:: whatsnew/v0.13.2.rst
+.. include:: whatsnew/v0.14.0.rst
 .. include:: whatsnew/v0.13.1.rst
 .. include:: whatsnew/v0.13.0.rst
 .. include:: whatsnew/v0.12.0.rst

docs/sphinx/source/whatsnew/v0.13.2.rst docs/sphinx/source/whatsnew/v0.14.0.rstdocs/sphinx/source/whatsnew/v0.13.2.rst renamed to docs/sphinx/source/whatsnew/v0.14.0.rst

@@ -1,22 +1,17 @@
-.. _whatsnew_0_13_2:
+.. _whatsnew_0_14_0:
 
 
-v0.13.2 (Anticipated December, 2025)
-------------------------------------
+v0.14.0 (January 16, 2026)
+--------------------------
 
 Breaking Changes
 ~~~~~~~~~~~~~~~~
 * Following the removal of the NSRDB PSM3 API, the :func:`!pvlib.iotools.get_psm3`,
   :func:`!pvlib.iotools.read_psm3`, and :func:`!pvlib.iotools.parse_psm3`
   functions are removed. (:issue:`2581`, :pull:`2582`)
-
-
-Deprecations
-~~~~~~~~~~~~
-
-
-Bug fixes
-~~~~~~~~~
+* Rename output column names to be prefixed with ``"poa_"`` when ``return_components=True``
+  in :py:func:`~pvlib.irradiance.haydavies`, :py:func:`~pvlib.irradiance.perez`,
+  and :py:func:`~pvlib.irradiance.perez_driesse`. (:issue:`2529`, :pull:`2627`)
 
 Enhancements
 ~~~~~~~~~~~~
@@ -54,7 +49,6 @@ Documentation
 * Fix typo in parameter name ``atmos_refract`` in :py:func:`pvlib.solarposition.spa_python`
   and :py:func:`pvlib.spa.solar_position`. (:issue:`2532`, :pull:`2592`)
 
-
 Testing
 ~~~~~~~
 * Add Python 3.14 to test suite. (:pull:`2590`)
@@ -63,18 +57,9 @@ Testing
 * Correct argument and value order in :py:func:`~pvlib.tests.ivtools.test_sde`,
   in tests of :py:func:`~pvlib.ivtools.sde._fit_sandia_cocontent`. (:issue:`2613`, :pull:`2615`)
 
-
-Benchmarking
-~~~~~~~~~~~~
-
-
 Requirements
 ~~~~~~~~~~~~
-
-
-Maintenance
-~~~~~~~~~~~
-
+* Advance minimum solarfactors to v1.6.1. (:pull:`2656`)
 
 Contributors
 ~~~~~~~~~~~~
@@ -87,3 +72,9 @@ Contributors
 * Anton Driesse (:ghuser:`adriesse`)
 * Rajiv Daxini (:ghuser:`RDaxini`)
 * Kevin Anderson (:ghuser:`kandersolar`)
+* Mark Mikofski (:ghuser:`mikofski`)
+* Will Holmgren (:ghuser:`wholmgren`)
+* Ioannis Sifnaios (:ghuser:`IoannisSifnaios`)
+* Mark Campanelli (:ghuser:`markcampanelli`)
+* Aman Srivastava (:ghuser:`aman-coder03`)
+* Vincent Filter (:ghuser:`vfilter`)

docs/sphinx/source/whatsnew/v0.13.3.rst docs/sphinx/source/whatsnew/v0.14.1.rstdocs/sphinx/source/whatsnew/v0.13.3.rst renamed to docs/sphinx/source/whatsnew/v0.14.1.rst

@@ -1,7 +1,7 @@
-.. _whatsnew_0_13_3:
+.. _whatsnew_0_14_1:
 
 
-v0.13.3 (Month XX, 20YY)
+v0.14.1 (Month XX, 20YY)
 -----------------------
 
 Breaking Changes

pvlib/bifacial/infinite_sheds.py

@@ -301,15 +301,16 @@ def get_irradiance_poa(surface_tilt, surface_azimuth, solar_zenith,
         sky_diffuse_comps_horizontal = haydavies(0, 180, dhi, dni, dni_extra,
                                                  solar_zenith, solar_azimuth,
                                                  return_components=True)
-        circumsolar_horizontal = sky_diffuse_comps_horizontal['circumsolar']
+        circumsolar_horizontal = \
+            sky_diffuse_comps_horizontal['poa_circumsolar']
 
         # Call haydavies a second time where circumsolar_normal is facing
         # directly towards sun, and can be added to DNI
         sky_diffuse_comps_normal = haydavies(solar_zenith, solar_azimuth, dhi,
                                              dni, dni_extra, solar_zenith,
                                              solar_azimuth,
                                              return_components=True)
-        circumsolar_normal = sky_diffuse_comps_normal['circumsolar']
+        circumsolar_normal = sky_diffuse_comps_normal['poa_circumsolar']
 
         dhi = dhi - circumsolar_horizontal
         dni = dni + circumsolar_normal

pvlib/irradiance.py

@@ -793,10 +793,11 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     diffuse_components : OrderedDict (array input) or DataFrame (Series input)
         Keys/columns are:
-            * sky_diffuse: Total sky diffuse
-            * isotropic
-            * circumsolar
-            * horizon (always zero, not accounted for by the Hay-Davies model)
+            * poa_sky_diffuse: Total sky diffuse
+            * poa_isotropic
+            * poa_circumsolar
+            * poa_horizon (always zero, not accounted for by the
+              Hay-Davies model)
 
     Notes
     ------
@@ -855,13 +856,13 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     if return_components:
         diffuse_components = OrderedDict()
-        diffuse_components['sky_diffuse'] = sky_diffuse
+        diffuse_components['poa_sky_diffuse'] = sky_diffuse
 
         # Calculate the individual components
-        diffuse_components['isotropic'] = poa_isotropic
-        diffuse_components['circumsolar'] = poa_circumsolar
-        diffuse_components['horizon'] = np.where(
-            np.isnan(diffuse_components['isotropic']), np.nan, 0.)
+        diffuse_components['poa_isotropic'] = poa_isotropic
+        diffuse_components['poa_circumsolar'] = poa_circumsolar
+        diffuse_components['poa_horizon'] = np.where(
+            np.isnan(diffuse_components['poa_isotropic']), np.nan, 0.)
 
         if isinstance(sky_diffuse, pd.Series):
             diffuse_components = pd.DataFrame(diffuse_components)
@@ -1111,10 +1112,10 @@ def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     diffuse_components : OrderedDict (array input) or DataFrame (Series input)
         Keys/columns are:
-            * sky_diffuse: Total sky diffuse
-            * isotropic
-            * circumsolar
-            * horizon
+            * poa_sky_diffuse: Total sky diffuse
+            * poa_isotropic
+            * poa_circumsolar
+            * poa_horizon
 
 
     References
@@ -1197,12 +1198,12 @@ def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     if return_components:
         diffuse_components = OrderedDict()
-        diffuse_components['sky_diffuse'] = sky_diffuse
+        diffuse_components['poa_sky_diffuse'] = sky_diffuse
 
         # Calculate the different components
-        diffuse_components['isotropic'] = dhi * term1
-        diffuse_components['circumsolar'] = dhi * term2
-        diffuse_components['horizon'] = dhi * term3
+        diffuse_components['poa_isotropic'] = dhi * term1
+        diffuse_components['poa_circumsolar'] = dhi * term2
+        diffuse_components['poa_horizon'] = dhi * term3
 
         # Set values of components to 0 when sky_diffuse is 0
         mask = sky_diffuse == 0
@@ -1353,10 +1354,10 @@ def perez_driesse(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     diffuse_components : OrderedDict (array input) or DataFrame (Series input)
         Keys/columns are:
-            * sky_diffuse: Total sky diffuse
-            * isotropic
-            * circumsolar
-            * horizon
+            * poa_sky_diffuse: Total sky diffuse
+            * poa_isotropic
+            * poa_circumsolar
+            * poa_horizon
 
     Notes
     -----
@@ -1417,12 +1418,12 @@ def perez_driesse(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     if return_components:
         diffuse_components = OrderedDict()
-        diffuse_components['sky_diffuse'] = sky_diffuse
+        diffuse_components['poa_sky_diffuse'] = sky_diffuse
 
         # Calculate the different components
-        diffuse_components['isotropic'] = dhi * term1
-        diffuse_components['circumsolar'] = dhi * term2
-        diffuse_components['horizon'] = dhi * term3
+        diffuse_components['poa_isotropic'] = dhi * term1
+        diffuse_components['poa_circumsolar'] = dhi * term2
+        diffuse_components['poa_horizon'] = dhi * term3
 
         if isinstance(sky_diffuse, pd.Series):
             diffuse_components = pd.DataFrame(diffuse_components)

pyproject.toml

@@ -50,7 +50,7 @@ optional = [
     'ephem',
     'nrel-pysam',
     'numba >= 0.17.0',
-    'solarfactors',
+    'solarfactors >= 1.6.1',
     'statsmodels',
 ]
 doc = [
@@ -64,7 +64,7 @@ doc = [
     'pillow',
     'sphinx-toggleprompt == 0.5.2',
     'sphinx-favicon',
-    'solarfactors',
+    'solarfactors >= 1.6.1',
     'sphinx-hoverxref ~= 1.4.2',  # when updating, check that _static/tooltipster_color_theming.css still works
 ]
 test = [

tests/test_irradiance.py

@@ -210,12 +210,14 @@ def test_haydavies(irrad_data, ephem_data, dni_et):
 
 
 def test_haydavies_components(irrad_data, ephem_data, dni_et):
+    keys = ['poa_sky_diffuse', 'poa_isotropic', 'poa_circumsolar',
+            'poa_horizon']
     expected = pd.DataFrame(np.array(
         [[0, 27.1775, 102.9949, 33.1909],
          [0, 27.1775, 30.1818, 27.9837],
          [0, 0, 72.8130, 5.2071],
          [0, 0, 0, 0]]).T,
-        columns=['sky_diffuse', 'isotropic', 'circumsolar', 'horizon'],
+        columns=keys,
         index=irrad_data.index
     )
     # pandas
@@ -229,23 +231,16 @@ def test_haydavies_components(irrad_data, ephem_data, dni_et):
         40, 180, irrad_data['dhi'].values, irrad_data['dni'].values, dni_et,
         ephem_data['apparent_zenith'].values, ephem_data['azimuth'].values,
         return_components=True)
-    assert_allclose(result['sky_diffuse'], expected['sky_diffuse'], atol=1e-4)
-    assert_allclose(result['isotropic'], expected['isotropic'], atol=1e-4)
-    assert_allclose(result['circumsolar'], expected['circumsolar'], atol=1e-4)
-    assert_allclose(result['horizon'], expected['horizon'], atol=1e-4)
+    for key in keys:
+        assert_allclose(result[key], expected[key], atol=1e-4)
     assert isinstance(result, dict)
     # scalar
     result = irradiance.haydavies(
         40, 180, irrad_data['dhi'].values[-1], irrad_data['dni'].values[-1],
         dni_et[-1], ephem_data['apparent_zenith'].values[-1],
         ephem_data['azimuth'].values[-1], return_components=True)
-    assert_allclose(result['sky_diffuse'], expected['sky_diffuse'].iloc[-1],
-                    atol=1e-4)
-    assert_allclose(result['isotropic'], expected['isotropic'].iloc[-1],
-                    atol=1e-4)
-    assert_allclose(result['circumsolar'], expected['circumsolar'].iloc[-1],
-                    atol=1e-4)
-    assert_allclose(result['horizon'], expected['horizon'].iloc[-1], atol=1e-4)
+    for key in keys:
+        assert_allclose(result[key], expected[key].iloc[-1], atol=1e-4)
     assert isinstance(result, dict)
 
 
@@ -312,13 +307,14 @@ def test_perez_components(irrad_data, ephem_data, dni_et, relative_airmass):
          [0.,  26.84138589,          np.nan,  31.72696071],
          [0.,  0.,         np.nan,  4.47966439],
          [0.,  4.62212181,         np.nan,  9.25316454]]).T,
-        columns=['sky_diffuse', 'isotropic', 'circumsolar', 'horizon'],
+        columns=['poa_sky_diffuse', 'poa_isotropic', 'poa_circumsolar',
+                 'poa_horizon'],
         index=irrad_data.index
     )
-    expected_for_sum = expected['sky_diffuse'].copy()
+    expected_for_sum = expected['poa_sky_diffuse'].copy()
     expected_for_sum.iloc[2] = 0
     sum_components = out.iloc[:, 1:].sum(axis=1)
-    sum_components.name = 'sky_diffuse'
+    sum_components.name = 'poa_sky_diffuse'
 
     assert_frame_equal(out, expected, check_less_precise=2)
     assert_series_equal(sum_components, expected_for_sum, check_less_precise=2)
@@ -338,13 +334,14 @@ def test_perez_driesse_components(irrad_data, ephem_data, dni_et,
          [0., 25.806, np.nan, 33.181],
          [0.,  0.000, np.nan,  4.197],
          [0.,  4.184, np.nan, 10.018]]).T,
-        columns=['sky_diffuse', 'isotropic', 'circumsolar', 'horizon'],
+        columns=['poa_sky_diffuse', 'poa_isotropic', 'poa_circumsolar',
+                 'poa_horizon'],
         index=irrad_data.index
     )
-    expected_for_sum = expected['sky_diffuse'].copy()
+    expected_for_sum = expected['poa_sky_diffuse'].copy()
     expected_for_sum.iloc[2] = 0
     sum_components = out.iloc[:, 1:].sum(axis=1)
-    sum_components.name = 'sky_diffuse'
+    sum_components.name = 'poa_sky_diffuse'
 
     assert_frame_equal(out, expected, check_less_precise=2)
     assert_series_equal(sum_components, expected_for_sum, check_less_precise=2)
@@ -384,13 +381,14 @@ def test_perez_negative_horizon():
          [166.785419, 142.24475, 119.173875, 83.525150, 45.725931],
          [113.548755,  16.09757,   9.956174,  3.142467,  0],
          [1.076010,  -6.13353,  -5.262151, -3.831230, -2.208923]]).T,
-        columns=['sky_diffuse', 'isotropic', 'circumsolar', 'horizon'],
+        columns=['poa_sky_diffuse', 'poa_isotropic', 'poa_circumsolar',
+                 'poa_horizon'],
         index=times
     )
 
-    expected_for_sum = expected['sky_diffuse'].copy()
+    expected_for_sum = expected['poa_sky_diffuse'].copy()
     sum_components = out.iloc[:, 1:].sum(axis=1)
-    sum_components.name = 'sky_diffuse'
+    sum_components.name = 'poa_sky_diffuse'
 
     assert_frame_equal(out, expected, check_less_precise=2)
     assert_series_equal(sum_components, expected_for_sum, check_less_precise=2)