Merge branch 'main' into refactor-docstring-params-2

Author: echedey-ls

.github/workflows/publish.yml

@@ -28,14 +28,18 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         python -m pip install build
+        python -m pip install twine
 
     - name: Build packages
       run: python -m build
 
+    - name: Check metadata verification
+      run: python -m twine check --strict dist/*
+
     # only publish distribution to PyPI for tagged commits
     - name: Publish distribution to PyPI
       if: startsWith(github.ref, 'refs/tags/v')
       uses: pypa/gh-action-pypi-publish@release/v1
       with:
         user: __token__
-        password: ${{ secrets.pypi_password }}
+        password: ${{ secrets.pypi_password }}

benchmarks/benchmarks/location.py

@@ -4,7 +4,7 @@
 
 import pandas as pd
 import pvlib
-from pkg_resources import parse_version
+from packaging.version import Version
 
 
 def set_solar_position(obj):
@@ -37,7 +37,7 @@ def time_location_get_clearsky(self):
 class Location_0_6_1:
 
     def setup(self):
-        if parse_version(pvlib.__version__) < parse_version('0.6.1'):
+        if Version(pvlib.__version__) < Version('0.6.1'):
             raise NotImplementedError
 
         set_solar_position(self)

benchmarks/benchmarks/solarposition.py

@@ -7,10 +7,10 @@
 import pvlib
 from pvlib import solarposition
 
-from pkg_resources import parse_version
+from packaging.version import Version
 
 
-if parse_version(pvlib.__version__) >= parse_version('0.6.1'):
+if Version(pvlib.__version__) >= Version('0.6.1'):
     sun_rise_set_transit_spa = solarposition.sun_rise_set_transit_spa
 else:
     sun_rise_set_transit_spa = solarposition.get_sun_rise_set_transit

benchmarks/benchmarks/solarposition_numba.py

@@ -7,7 +7,7 @@
 Try to keep relevant sections in sync with benchmarks/solarposition.py
 """
 
-from pkg_resources import parse_version
+from packaging.version import Version
 import pandas as pd
 
 import os
@@ -18,7 +18,7 @@
 from pvlib import solarposition  # NOQA: E402
 
 
-if parse_version(pvlib.__version__) >= parse_version('0.6.1'):
+if Version(pvlib.__version__) >= Version('0.6.1'):
     sun_rise_set_transit_spa = solarposition.sun_rise_set_transit_spa
 else:
     sun_rise_set_transit_spa = solarposition.get_sun_rise_set_transit

benchmarks/benchmarks/temperature.py

@@ -4,7 +4,7 @@
 
 import pandas as pd
 import pvlib
-from pkg_resources import parse_version
+from packaging.version import Version
 from functools import partial
 
 
@@ -20,7 +20,7 @@ class SAPM:
 
     def setup(self):
         set_weather_data(self)
-        if parse_version(pvlib.__version__) >= parse_version('0.7.0'):
+        if Version(pvlib.__version__) >= Version('0.7.0'):
             kwargs = pvlib.temperature.TEMPERATURE_MODEL_PARAMETERS['sapm']
             kwargs = kwargs['open_rack_glass_glass']
             self.sapm_cell_wrapper = partial(pvlib.temperature.sapm_cell,
@@ -41,7 +41,7 @@ def time_sapm_cell(self):
 class Fuentes:
 
     def setup(self):
-        if parse_version(pvlib.__version__) < parse_version('0.8.0'):
+        if Version(pvlib.__version__) < Version('0.8.0'):
             raise NotImplementedError
 
         set_weather_data(self)

docs/examples/irradiance-decomposition/plot_diffuse_fraction.py

@@ -203,7 +203,7 @@
 # `NSRDB`_ user manuals.
 #
 # The Erbs and Boland models are correlations only based on the clearness index
-# kt, which is the ratio of GHI to the the horizontal component of the
+# kt, which is the ratio of GHI to the horizontal component of the
 # extra-terrestrial irradiance. At low sun elevation (zenith near 90 degrees),
 # especially near sunset, kt can explode because the denominator
 # (extra-terrestrial irradiance) approaches zero. In pvlib this behavior is

docs/examples/iv-modeling/plot_singlediode.py

@@ -118,7 +118,6 @@
 plt.xlabel('Module voltage [V]')
 plt.ylabel('Module current [A]')
 plt.title(parameters['Name'])
-plt.show()
 plt.gcf().set_tight_layout(True)
 
 
@@ -136,6 +135,7 @@ def draw_arrow(ax, label, x0, y0, rotation, size, direction):
 ax = plt.gca()
 draw_arrow(ax, 'Irradiance', 20, 2.5, 90, 15, 'r')
 draw_arrow(ax, 'Temperature', 35, 1, 0, 15, 'l')
+plt.show()
 
 print(pd.DataFrame({
     'i_sc': curve_info['i_sc'],

docs/examples/shading/plot_simple_irradiance_adjustment_for_horizon_shading.py

@@ -0,0 +1,118 @@
+"""
+Simple irradiance adjustment for horizon shading
+================================================
+
+Example of applying horizon shading to dni and global poa. Using
+horizon profile data, this example interpolates it to time-series
+solar-position data, and adjust DNI and POA-global irradiance.
+"""
+
+# %%
+# This example shows how to use horizon elevation angles with
+# corresponding horizon azimuth angles for simple horizon shading adjustments.
+#
+# After location information and a date range is established, solar position
+# data is calculated using :py:func:`pvlib.solarposition.get_solarposition`.
+# Horizon data is assigned, and interpolated to the solar azimuth time
+# series data. Finally, in times when solar elevation is greater than the
+# interpolated horizon elevation angle, DNI is set to 0.
+
+import numpy as np
+import pandas as pd
+import pvlib
+
+# Golden, CO
+latitude, longitude = 39.76, -105.22
+tz = 'MST'
+
+# Set times in the morning of the December solstice.
+times = pd.date_range(
+    '2020-12-20 6:30', '2020-12-20 9:00', freq='1T', tz=tz
+)
+
+# Create location object, and get solar position and clearsky irradiance data.
+location = pvlib.location.Location(latitude, longitude, tz)
+solar_position = location.get_solarposition(times)
+clearsky = location.get_clearsky(times)
+
+# Assign variable names for easier reading.
+surface_tilt = 30
+surface_azimuth = 180
+solar_azimuth = solar_position.azimuth
+solar_zenith = solar_position.apparent_zenith
+solar_elevation = solar_position.apparent_elevation
+dni = clearsky.dni
+ghi = clearsky.ghi
+dhi = clearsky.dhi
+
+# %%
+# With basic inputs in place, let's perform the adjustment for horizon shading:
+
+# Use hard-coded horizon profile data from location object above.
+horizon_profile = pd.Series([
+    10.7, 11.8, 11.5, 10.3, 8.0, 6.5, 3.8, 2.3, 2.3, 2.3, 4.6, 8.0, 10.3, 11.1,
+    10.7, 10.3, 9.2, 6.1, 5.3, 2.3, 3.1, 1.9, 1.9, 2.7, 3.8, 5.3, 6.5, 8.4,
+    8.8, 8.4, 8.4, 8.4, 6.5, 6.1, 6.5, 6.1, 7.3, 9.2, 8.4, 8.0, 5.7, 5.3, 5.3,
+    4.2, 4.2, 4.2, 7.3, 9.5
+], index=np.arange(0, 360, 7.5))
+
+ax = horizon_profile.plot(xlim=(0, 360), ylim=(0, None), figsize=(6, 2.5))
+ax.set_title('Horizon profile')
+ax.set_xticks([0, 90, 180, 270, 360])
+ax.set_xlabel('Azimuth [°]')
+ax.set_ylabel('Horizon angle [°]')
+
+# %%
+# .. admonition:: Horizon data from PVGIS
+#
+#     Example of how to get the above horizon data from PVGIS
+#
+#     horizon_profile, horizon_metadata = pvlib.iotools.get_pvgis_horizon(
+#         latitutde, longitude)
+#
+
+# Interpolate the horizon elevation data to the solar azimuth, and keep as a
+# numpy array.
+horizon_elevation_data = np.interp(
+    solar_azimuth, horizon_profile.index, horizon_profile
+)
+
+# Convert to Pandas Series for easier usage.
+horizon_elevation_data = pd.Series(horizon_elevation_data, times)
+
+# Adjust DNI based on data - note this is returned as numpy array
+dni_adjusted = np.where(solar_elevation > horizon_elevation_data, dni, 0)
+
+# Adjust GHI and set it to DHI for time-periods where 'dni_adjusted' is 0.
+# Note this is returned as numpy array
+ghi_adjusted = np.where(dni_adjusted == 0, dhi, ghi)
+
+# Transposition using the original and adjusted irradiance components.
+irrad_pre_adj = pvlib.irradiance.get_total_irradiance(
+    surface_tilt, surface_azimuth, solar_zenith, solar_azimuth, dni, ghi, dhi
+)
+
+irrad_post_adj = pvlib.irradiance.get_total_irradiance(
+    surface_tilt, surface_azimuth, solar_zenith, solar_azimuth, dni_adjusted,
+    ghi_adjusted, dhi
+)
+
+# Create and plot result DataFrames.
+poa_global_comparison = pd.DataFrame({
+    'poa_global_pre-adjustment': irrad_pre_adj.poa_global,
+    'poa_global_post-adjustment': irrad_post_adj.poa_global
+})
+
+dni_comparison = pd.DataFrame({
+    'dni_pre-adjustment': dni,
+    'dni_post-adjustment': dni_adjusted
+})
+
+# Plot results
+poa_global_comparison.plot(
+    title='POA-Global: Before and after Horizon Adjustment',
+    ylabel='Irradiance'
+)
+dni_comparison.plot(
+    title='DNI: Before and after Horizon Adjustment', ylabel='Irradiance'
+)

docs/sphinx/source/reference/iotools.rst

@@ -42,6 +42,8 @@ of sources and file formats relevant to solar energy modeling.
    iotools.get_acis_mpe
    iotools.get_acis_station_data
    iotools.get_acis_available_stations
+   iotools.read_panond
+
 
 A :py:class:`~pvlib.location.Location` object may be created from metadata
 in some files.

docs/sphinx/source/reference/irradiance/decomposition.rst

@@ -12,6 +12,7 @@ DNI estimation models
    irradiance.dirint
    irradiance.dirindex
    irradiance.erbs
+   irradiance.erbs_driesse
    irradiance.orgill_hollands
    irradiance.boland
    irradiance.campbell_norman

docs/sphinx/source/reference/irradiance/transposition.rst

@@ -10,6 +10,7 @@ Transposition models
    irradiance.get_sky_diffuse
    irradiance.isotropic
    irradiance.perez
+   irradiance.perez_driesse
    irradiance.haydavies
    irradiance.klucher
    irradiance.reindl

docs/sphinx/source/user_guide/faq.rst

@@ -66,9 +66,11 @@ irradiance datasets, including the BSRN, SURFRAD, SRML, and NREL's MIDC.
 Can I use PVsyst (PAN/OND) files with pvlib?
 --------------------------------------------
 
-Currently, pvlib does not have the ability to import any PVsyst file formats.
-Certain formats of particular interest (e.g. PAN files) may be added in a future
-version.  Until then, these Google Group threads
+Although pvlib includes a function to read PAN and OND files
+(:py:func:`~pvlib.iotools.read_panond`), it is up to the user to determine
+whether and how the imported parameter values can be used with pvlib's models.
+Easier use of these parameter files with the rest of pvlib may be added
+in a future version.  Until then, these Google Group threads
 (`one <https://groups.google.com/g/pvlib-python/c/PDDic0SS6ao/m/Z-WKj7C6BwAJ>`_
 and `two <https://groups.google.com/g/pvlib-python/c/b1mf4Y1qHBY/m/tK2FBCJyBgAJ>`_)
 may be useful for some users.

docs/sphinx/source/whatsnew.rst

@@ -6,6 +6,7 @@ What's New
 
 These are new features and improvements of note in each release.
 
+.. include:: whatsnew/v0.10.2.rst
 .. include:: whatsnew/v0.10.1.rst
 .. include:: whatsnew/v0.10.0.rst
 .. include:: whatsnew/v0.9.5.rst

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

@@ -1,45 +1,86 @@
 .. _whatsnew_01020:
 
 
-v0.10.2 (Anticipated September, 2023)
--------------------------------------
-
-
-Deprecations
-~~~~~~~~~~~~
+v0.10.2 (September 21, 2023)
+----------------------------
 
 
 Enhancements
 ~~~~~~~~~~~~
+* Added .pan/.ond reader function :py:func:`pvlib.iotools.read_panond`. (:issue:`1747`, :pull:`1749`)
 * Added support for dates to be specified as strings in the iotools get functions:
-  :py:func:`pvlib.iotools.get_pvgis_hourly`, :py:func:`pvlib.iotools.get_cams`,
-  :py:func:`pvlib.iotools.get_bsrn`, and :py:func:`pvlib.iotools.read_midc_raw_data_from_nrel`.
+  :py:func:`~pvlib.iotools.get_pvgis_hourly`, :py:func:`~pvlib.iotools.get_cams`,
+  :py:func:`~pvlib.iotools.get_bsrn`, and :py:func:`~pvlib.iotools.read_midc_raw_data_from_nrel`.
   (:pull:`1800`)
-* Added option to infer threshold values for 
+* Added support for asymmetric limiting angles in :py:func:`pvlib.tracking.singleaxis`
+  and :py:class:`~pvlib.pvsystem.SingleAxisTrackerMount`. (:issue:`1777`, :pull:`1809`, :pull:`1852`)
+* Added option to infer threshold values for
   :py:func:`pvlib.clearsky.detect_clearsky` (:issue:`1808`, :pull:`1784`)
+* Added a continuous version of the Erbs diffuse-fraction/decomposition model.
+  :py:func:`pvlib.irradiance.erbs_driesse` (:issue:`1755`, :pull:`1834`)
+* Added :py:func:`~pvlib.iam.interp` option as AOI losses model in
+  :py:class:`~pvlib.modelchain.ModelChain` and
+  :py:class:`~pvlib.pvsystem.PVSystem`. (:issue:`1742`, :pull:`1832`)
+* :py:class:`~pvlib.pvsystem.PVSystem` objects with a single
+  :py:class:`~pvlib.pvsystem.Array` can now be created without wrapping the
+  ``Array`` in a list first. (:issue:`1831`, :pull:`1854`)
 
 
 Bug fixes
 ~~~~~~~~~
 * :py:func:`~pvlib.iotools.get_psm3` no longer incorrectly returns clear-sky
   DHI instead of clear-sky GHI when requesting ``ghi_clear``. (:pull:`1819`)
+* :py:func:`pvlib.singlediode.bishop88` with ``method='newton'`` no longer
+  crashes when passed ``pandas.Series`` of length one.
+  (:issue:`1787`, :pull:`1822`)
+* :py:class:`~pvlib.pvsystem.PVSystem` now correctly passes ``n_ar`` module
+  parameter to :py:func:`pvlib.iam.physical` when this IAM model is specified
+  or inferred. (:pull:`1832`)
+
 
 Testing
 ~~~~~~~
 * Added GitHub action to lint file changes with Flake8, replacing Stickler-CI.
-  (:issue:`776`, :issue:`1722`, :pull:`1786`)
+  (:issue:`776`, :issue:`1722`, :pull:`1723`, :pull:`1786`)
+
 
 Documentation
 ~~~~~~~~~~~~~
-* Removed Stickler-CI integration as the service has ceased June 2023.
-  (:issue:`1722`, :pull:`1723`)
-
-Requirements
-~~~~~~~~~~~~
+* Added docstring detail for :py:func:`pvlib.iam.schlick_diffuse`.
+  (:issue:`1811`, :pull:`1812`)
+* Specified that :py:func:`pvlib.singlediode.bishop88`,
+  :py:func:`pvlib.singlediode.bishop88_i_from_v`, and
+  :py:func:`pvlib.singlediode.bishop88_v_from_i` parameters ``breakdown_factor``,
+  ``breakdown_voltage``, and ``breakdown_exp`` should be floats.
+  (:issue:`1820`, :pull:`1821`)
+* Fix and update example in :py:func:`pvlib.pvsystem.retrieve_sam`.
+  (:issue:`1741`, :pull:`1833`)
+* Fix error in :py:func:`pvlib.iotools.get_pvgis_hourly` documentation of ``surface_azimuth``.
+  (:issue:`1724`, :pull:`1838`)
+* Update definition of ``snow_events`` parameter for :py:func:`pvlib.snow.loss_townsend`.
+  (:issue:`1839`, :pull:`1840`)
+* Added gallery example demonstrating how horizon profile data from :py:func:`pvlib.iotools.get_pvgis_horizon`, 
+  can be used to apply horizon shading to time series dni and global poa data. (:pull:`1849`)
 
 
 Contributors
 ~~~~~~~~~~~~
+* Connor Krening (:ghuser:`ckrening`)
 * Adam R. Jensen (:ghuser:`AdamRJensen`)
+* Michal Arieli (:ghuser:`MichalArieli`)
 * Abigail Jones (:ghuser:`ajonesr`)
 * Taos Transue (:ghuser:`reepoi`)
+* Echedey Luis (:ghuser:`echedey-ls`)
+* Todd Karin (:ghuser:`toddkarin`)
+* NativeSci (:ghuser:`nativesci`)
+* Anton Driesse (:ghuser:`adriesse`)
+* Lukas Grossar (:ghuser:`tongpu`)
+* Areeba Turabi (:ghuser:`aturabi`)
+* Saurabh Aneja (:ghuser:`spaneja`)
+* Miroslav Šedivý (:ghuser:`eumiro`)
+* kjsauer (:ghuser:`kjsauer`)
+* Jules Chéron (:ghuser:`jules-ch`)
+* Cliff Hansen (:ghuser:`cwhanse`)
+* Will Holmgren (:ghuser:`wholmgren`)
+* Mark Mikofski (:ghuser:`mikofski`)
+* Kevin Anderson (:ghuser:`kandersolar`)