Merge remote-tracking branch 'upstream/main' into rename-solar-position-tracking.singlaxis

AdamRJensen · AdamRJensen · commit 2eaff7eb57de · 2025-06-08T16:24:56.000-04:00
diff --git a/docs/sphinx/source/whatsnew.rst b/docs/sphinx/source/whatsnew.rst
@@ -6,7 +6,8 @@ What's New
 
 These are new features and improvements of note in each release.
 
-.. include:: whatsnew/v0.12.1.rst
+.. include:: whatsnew/v0.13.1.rst
+.. include:: whatsnew/v0.13.0.rst
 .. include:: whatsnew/v0.12.0.rst
 .. include:: whatsnew/v0.11.2.rst
 .. include:: whatsnew/v0.11.1.rst
diff --git a/docs/sphinx/source/whatsnew/v0.13.0.rst b/docs/sphinx/source/whatsnew/v0.13.0.rst
@@ -1,8 +1,8 @@
-.. _whatsnew_01201:
+.. _whatsnew_01300:
 
 
-v0.12.1 (XXXX, 2025)
-------------------------
+v0.13.0 (June 7, 2025)
+----------------------
 
 Breaking Changes
 ~~~~~~~~~~~~~~~~
@@ -15,6 +15,9 @@ Breaking Changes
   :py:func:`~pvlib.iotools.get_pvgis_tmy` now return ``(data,meta)``
   following the iotools convention instead of ``(data,months_selected,inputs,meta)``.
   (:pull:`2470`)
+* :py:func:`~pvlib.iotools.get_pvgis_tmy` now defaults to ``coerce_year=1990``,
+  whereas the default behavior previously was to use the years of the selected
+  months for the TMY index. (:pull:`2474`)
 * Remove ``outputformat='basic'`` option in :py:func:`~pvlib.iotools.get_pvgis_tmy`.
   (:pull:`2416`)
 
@@ -51,7 +54,7 @@ Enhancements
   :py:class:`~pvlib.pvsystem.PVSystem` and :py:class:`~pvlib.modelchain.ModelChain`.
   (:issue:`2402`, :pull:`2433`)
 * Add optional arguments ``temperature_ref`` and ``irradiance_ref`` to
-  :py:func:`~pvlib.pvsystem.sapm`(:issue:`2432`, :pull:`2434`)
+  :py:func:`~pvlib.pvsystem.sapm` (:issue:`2432`, :pull:`2434`)
 * Add NREL NSRDB PSM v4 API client to :py:mod:`pvlib.iotools`. See
   :py:func:`~pvlib.iotools.get_nsrdb_psm4_aggregated`,
   :py:func:`~pvlib.iotools.get_nsrdb_psm4_tmy`,
@@ -72,7 +75,7 @@ Documentation
   :py:func:`~pvlib.pvsystem.sapm` (:issue:`2392`, :pull:`2435`)
 * Add gallery example on calculating irradiance at crop level for agriPV systems.
   (:pull:`2459`)
-* Update references in :py:func`~pvlib.irradiance.get_extra_radiation`
+* Update references in :py:func:`~pvlib.irradiance.get_extra_radiation`
   (:issue:`2333`, :pull:`2347`)
 * Update references in :py:func:`~pvlib.iotools.get_cams` and :py:func:`~pvlib.iotools.read_cams`
   (:issue:`2427`, :pull:`2457`)
@@ -83,16 +86,11 @@ Requirements
 ~~~~~~~~~~~~
 * ``wheel`` is no longer a build dependency. (:pull:`2439`)
 
-Testing
-~~~~~~~
-
-
 Maintenance
 ~~~~~~~~~~~
 * Update ``pyproject.toml`` to replace deprecated license table and
   classifiers. (:issue:`2440`, :pull:`2441`)
 
-
 Contributors
 ~~~~~~~~~~~~
 * Cliff Hansen (:ghuser:`cwhanse`)
@@ -105,3 +103,10 @@ Contributors
 * omahs (:ghuser:`omahs`)
 * Adam R. Jensen (:ghuser:`AdamRJensen`)
 * Marion Schroedter-Homscheidt (:ghuser:`mschroedter`)
+* Anton Driesse (:ghuser:`adriesse`)
+* Mark Mikofski (:ghuser:`mikofski`)
+* Ioannis Sifnaios (:ghuser:`IoannisSifnaios`)
+* Mark Campanelli (:ghuser:`markcampanelli`)
+* Paul Gilman (:ghuser:`cpaulgilman`)
+* Yu Xie (:ghuser:`xieyupku`)
+* Grant Buster (:ghuser:`grantbuster`)
diff --git a/docs/sphinx/source/whatsnew/v0.13.1.rst b/docs/sphinx/source/whatsnew/v0.13.1.rst
@@ -0,0 +1,45 @@
+.. _whatsnew_0_13_1:
+
+
+v0.13.1 (Anticipated September, 2025)
+-------------------------------------
+
+Breaking Changes
+~~~~~~~~~~~~~~~~
+
+
+Deprecations
+~~~~~~~~~~~~
+
+
+Bug fixes
+~~~~~~~~~
+
+
+Enhancements
+~~~~~~~~~~~~
+
+
+Documentation
+~~~~~~~~~~~~~
+
+
+Testing
+~~~~~~~
+
+
+Benchmarking
+~~~~~~~~~~~~
+
+
+Requirements
+~~~~~~~~~~~~
+
+
+Maintenance
+~~~~~~~~~~~
+
+
+Contributors
+~~~~~~~~~~~~
+
diff --git a/pvlib/iotools/bsrn.py b/pvlib/iotools/bsrn.py
@@ -162,8 +162,7 @@ def get_bsrn(station, start, end, username, password,
     end = pd.to_datetime(end)
 
     # Generate list files to download based on start/end (SSSMMYY.dat.gz)
-    filenames = pd.date_range(
-        start, end.replace(day=1) + pd.DateOffset(months=1), freq='1M')\
+    filenames = pd.date_range(start.date().replace(day=1), end, freq='1MS')\
         .strftime(f"{station}%m%y.dat.gz").tolist()
 
     # Create FTP connection
diff --git a/pvlib/iotools/psm3.py b/pvlib/iotools/psm3.py
@@ -361,5 +361,5 @@ def read_psm3(filename, map_variables=True):
     return data, metadata
 
 
-parse_psm3 = deprecated(since="0.12.1", name="parse_psm3",
+parse_psm3 = deprecated(since="0.13.0", name="parse_psm3",
                         alternative="read_psm3")(read_psm3)
diff --git a/pvlib/iotools/psm4.py b/pvlib/iotools/psm4.py
@@ -72,7 +72,7 @@
 
 
 def get_nsrdb_psm4_aggregated(latitude, longitude, api_key, email,
-                              year='2023', time_step=60,
+                              year, time_step=60,
                               parameters=PARAMETERS, leap_day=True,
                               full_name=PVLIB_PYTHON,
                               affiliation=PVLIB_PYTHON,
@@ -96,7 +96,7 @@ def get_nsrdb_psm4_aggregated(latitude, longitude, api_key, email,
     email : str
         NREL API uses this to automatically communicate messages back
         to the user only if necessary
-    year : str, default '2023'
+    year : int or str
         PSM4 API parameter specifing year (e.g. ``2023``) to download. The
         allowed values update periodically, so consult the NSRDB reference
         below for the current set of options. Called ``names`` in NSRDB API.
@@ -173,9 +173,6 @@ def get_nsrdb_psm4_aggregated(latitude, longitude, api_key, email,
     latitude = ('%8.4f' % latitude).strip()
     # TODO: make format_WKT(object_type, *args) in tools.py
 
-    # convert to string to accomodate integer years being passed in
-    year = str(year)
-
     # convert pvlib names in parameters to PSM4 convention
     parameters = [REQUEST_VARIABLE_MAP.get(a, a) for a in parameters]
 
@@ -314,9 +311,6 @@ def get_nsrdb_psm4_tmy(latitude, longitude, api_key, email, year='tmy',
     latitude = ('%8.4f' % latitude).strip()
     # TODO: make format_WKT(object_type, *args) in tools.py
 
-    # convert to string to accomodate integer years being passed in
-    year = str(year)
-
     # convert pvlib names in parameters to PSM4 convention
     parameters = [REQUEST_VARIABLE_MAP.get(a, a) for a in parameters]
 
@@ -354,7 +348,7 @@ def get_nsrdb_psm4_tmy(latitude, longitude, api_key, email, year='tmy',
     return read_nsrdb_psm4(fbuf, map_variables)
 
 
-def get_nsrdb_psm4_conus(latitude, longitude, api_key, email, year='2023',
+def get_nsrdb_psm4_conus(latitude, longitude, api_key, email, year,
                          time_step=60, parameters=PARAMETERS, leap_day=True,
                          full_name=PVLIB_PYTHON, affiliation=PVLIB_PYTHON,
                          utc=False, map_variables=True, url=None, timeout=30):
@@ -376,7 +370,7 @@ def get_nsrdb_psm4_conus(latitude, longitude, api_key, email, year='2023',
     email : str
         NREL API uses this to automatically communicate messages back
         to the user only if necessary
-    year : str, default '2023'
+    year : int or str
         PSM4 API parameter specifing year (e.g. ``2023``) to download. The
         allowed values update periodically, so consult the NSRDB reference
         below for the current set of options. Called ``names`` in NSRDB API.
@@ -453,9 +447,6 @@ def get_nsrdb_psm4_conus(latitude, longitude, api_key, email, year='2023',
     latitude = ('%8.4f' % latitude).strip()
     # TODO: make format_WKT(object_type, *args) in tools.py
 
-    # convert to string to accomodate integer years being passed in
-    year = str(year)
-
     # convert pvlib names in parameters to PSM4 convention
     parameters = [REQUEST_VARIABLE_MAP.get(a, a) for a in parameters]
 
@@ -494,7 +485,7 @@ def get_nsrdb_psm4_conus(latitude, longitude, api_key, email, year='2023',
 
 
 def get_nsrdb_psm4_full_disc(latitude, longitude, api_key, email,
-                             year='2023', time_step=60,
+                             year, time_step=60,
                              parameters=PARAMETERS, leap_day=True,
                              full_name=PVLIB_PYTHON,
                              affiliation=PVLIB_PYTHON, utc=False,
@@ -517,7 +508,7 @@ def get_nsrdb_psm4_full_disc(latitude, longitude, api_key, email,
     email : str
         NREL API uses this to automatically communicate messages back
         to the user only if necessary
-    year : str, default '2023'
+    year : int or str
         PSM4 API parameter specifing year (e.g. ``2023``) to download. The
         allowed values update periodically, so consult the NSRDB reference
         below for the current set of options. Called ``names`` in NSRDB API.
@@ -595,9 +586,6 @@ def get_nsrdb_psm4_full_disc(latitude, longitude, api_key, email,
     latitude = ('%8.4f' % latitude).strip()
     # TODO: make format_WKT(object_type, *args) in tools.py
 
-    # convert to string to accomodate integer years being passed in
-    year = str(year)
-
     # convert pvlib names in parameters to PSM4 convention
     parameters = [REQUEST_VARIABLE_MAP.get(a, a) for a in parameters]
 
diff --git a/pvlib/iotools/pvgis.py b/pvlib/iotools/pvgis.py
@@ -434,7 +434,7 @@ def _coerce_and_roll_tmy(tmy_data, tz, year):
 def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
                   userhorizon=None, startyear=None, endyear=None,
                   map_variables=True, url=URL, timeout=30,
-                  roll_utc_offset=None, coerce_year=None):
+                  roll_utc_offset=None, coerce_year=1990):
     """
     Get TMY data from PVGIS.
 
@@ -477,9 +477,11 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
         Use to specify a time zone other than the default UTC zero and roll
         dataframe by ``roll_utc_offset`` so it starts at midnight on January
         1st. Ignored if ``None``, otherwise will force year to ``coerce_year``.
-    coerce_year: int, optional
-        Use to force indices to desired year. Will default to 1990 if
-        ``coerce_year`` is not specified, but ``roll_utc_offset`` is specified.
+    coerce_year: int, default 1990
+        Use to force indices to desired year. Defaults to 1990. Specify
+        ``None`` to return the actual indices used for the TMY. If
+        ``coerce_year`` is ``None``, but ``roll_utc_offset`` is specified,
+        then ``coerce_year`` will be set to the default.
 
     Returns
     -------
diff --git a/pvlib/iotools/sodapro.py b/pvlib/iotools/sodapro.py
@@ -359,5 +359,5 @@ def read_cams(filename, integrated=False, label=None, map_variables=True):
     return data, metadata
 
 
-parse_cams = deprecated(since="0.12.1", name="parse_cams",
+parse_cams = deprecated(since="0.13.0", name="parse_cams",
                         alternative="read_cams")(read_cams)
diff --git a/pvlib/iotools/srml.py b/pvlib/iotools/srml.py
@@ -236,8 +236,7 @@ def get_srml(station, start, end, filetype='PO', map_variables=True,
     end = pd.to_datetime(end)
 
     # Generate list of months
-    months = pd.date_range(
-        start, end.replace(day=1) + pd.DateOffset(months=1), freq='1M')
+    months = pd.date_range(start.date().replace(day=1), end, freq='1MS')
     months_str = months.strftime('%y%m')
 
     # Generate list of filenames
diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py
@@ -1627,7 +1627,7 @@ def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
     since='0.11.2',
     old_param_name='clearsky_ghi',
     new_param_name='ghi_clear',
-    removal="0.13.0")
+    removal="0.14.0")
 def clearsky_index(ghi, ghi_clear, max_clearsky_index=2.0):
     """
     Calculate the clearsky index.
@@ -2172,12 +2172,12 @@ def _dirint_bins(times, kt_prime, zenith, w, delta_kt_prime):
     since='0.11.2',
     old_param_name='ghi_clearsky',
     new_param_name='ghi_clear',
-    removal="0.13.0")
+    removal="0.14.0")
 @renamed_kwarg_warning(
     since='0.11.2',
     old_param_name='dni_clearsky',
     new_param_name='dni_clear',
-    removal="0.13.0")
+    removal="0.14.0")
 def dirindex(ghi, ghi_clear, dni_clear, zenith, times, pressure=101325.,
              use_delta_kt_prime=True, temp_dew=None, min_cos_zenith=0.065,
              max_zenith=87):
@@ -3662,7 +3662,7 @@ def _get_dirint_coeffs():
     since='0.11.2',
     old_param_name='clearsky_dni',
     new_param_name='dni_clear',
-    removal="0.13.0")
+    removal="0.14.0")
 def dni(ghi, dhi, zenith, dni_clear=None, clearsky_tolerance=1.1,
         zenith_threshold_for_zero_dni=88.0,
         zenith_threshold_for_clearsky_limit=80.0):
diff --git a/tests/iotools/test_pvgis.py b/tests/iotools/test_pvgis.py
@@ -384,7 +384,7 @@ def pvgis_tmy_mapped_columns():
 @pytest.mark.flaky(reruns=RERUNS, reruns_delay=RERUNS_DELAY)
 def test_get_pvgis_tmy(expected, month_year_expected, inputs_expected,
                        meta_expected):
-    pvgis_data = get_pvgis_tmy(45, 8, map_variables=False)
+    pvgis_data = get_pvgis_tmy(45, 8, map_variables=False, coerce_year=None)
     _compare_pvgis_tmy_json(expected, month_year_expected, inputs_expected,
                             meta_expected, pvgis_data)
 
@@ -428,7 +428,8 @@ def test_get_pvgis_tmy_kwargs(userhorizon_expected):
     _, meta = get_pvgis_tmy(45, 8, usehorizon=False, map_variables=False)
     assert meta['inputs']['meteo_data']['use_horizon'] is False
     data, _ = get_pvgis_tmy(
-        45, 8, userhorizon=[0, 10, 20, 30, 40, 15, 25, 5], map_variables=False)
+        45, 8, userhorizon=[0, 10, 20, 30, 40, 15, 25, 5], map_variables=False,
+        coerce_year=None)
     assert np.allclose(
         data['G(h)'], userhorizon_expected['G(h)'].values)
     assert np.allclose(
@@ -486,13 +487,17 @@ def test_get_pvgis_tmy_coerce_year():
     for m, test_case in enumerate(noon_test_data):
         expected = pvgis_data[pvgis_data.index.month == m+1].iloc[12]
         assert all(test_case == expected)
+    # Test that get_pvgis_tmy defaults to coerce_year=1990
+    pvgis_data, _ = get_pvgis_tmy(45, 8)
+    assert all(pvgis_data.index.year == 1990)
 
 
 @pytest.mark.remote_data
 @pytest.mark.flaky(reruns=RERUNS, reruns_delay=RERUNS_DELAY)
 def test_get_pvgis_tmy_csv(expected, month_year_expected, inputs_expected,
-                           meta_expected, csv_meta):
-    pvgis_data = get_pvgis_tmy(45, 8, outputformat='csv', map_variables=False)
+                           meta_expected, csv_meta, coerce_year=None):
+    pvgis_data = get_pvgis_tmy(45, 8, outputformat='csv', map_variables=False,
+                               coerce_year=None)
     _compare_pvgis_tmy_csv(expected, month_year_expected, inputs_expected,
                            meta_expected, csv_meta, pvgis_data)
 
@@ -532,7 +537,8 @@ def _compare_pvgis_tmy_csv(expected, month_year_expected, inputs_expected,
 @pytest.mark.remote_data
 @pytest.mark.flaky(reruns=RERUNS, reruns_delay=RERUNS_DELAY)
 def test_get_pvgis_tmy_epw(expected, epw_meta):
-    pvgis_data = get_pvgis_tmy(45, 8, outputformat='epw', map_variables=False)
+    pvgis_data = get_pvgis_tmy(45, 8, outputformat='epw', map_variables=False,
+                               coerce_year=None)
     _compare_pvgis_tmy_epw(expected, epw_meta, pvgis_data)
 
 
diff --git a/tests/test_clearsky.py b/tests/test_clearsky.py
diff --git a/tests/test_irradiance.py b/tests/test_irradiance.py
