Merge branch 'main' into reference_styleguide

Author: RDaxini

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.11.2.rst
 .. include:: whatsnew/v0.11.1.rst
 .. include:: whatsnew/v0.11.0.rst
 .. include:: whatsnew/v0.10.5.rst

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

@@ -1,42 +1,40 @@
 .. _whatsnew_01110:
 
 
-v0.11.1 (Anticipated Sep, 2024)
--------------------------------
-
-Deprecations
-~~~~~~~~~~~~
-
+v0.11.1 (September 26, 2024)
+----------------------------
 
 Enhancements
 ~~~~~~~~~~~~
 * Add new function to calculate the average photon energy,
-  :py:func:`pvlib.spectrum.average_photon_energy`.
+  :py:func:`~pvlib.spectrum.average_photon_energy`.
   (:issue:`2135`, :pull:`2140`)
 * Add new losses function that accounts for non-uniform irradiance on bifacial
-  modules, :py:func:`pvlib.bifacial.power_mismatch_deline`.
+  modules, :py:func:`~pvlib.bifacial.power_mismatch_deline`.
   (:issue:`2045`, :pull:`2046`)
 * Add new parameters for min/max absolute air mass to
-  :py:func:`pvlib.spectrum.spectral_factor_firstsolar`.
+  :py:func:`~pvlib.spectrum.spectral_factor_firstsolar`.
   (:issue:`2086`, :pull:`2100`)
 * Add ``roll_utc_offset`` and ``coerce_year`` arguments to
-  :py:func:`pvlib.iotools.get_pvgis_tmy` to allow user to specify time zone,
+  :py:func:`~pvlib.iotools.get_pvgis_tmy` to allow user to specify time zone,
   rotate indices of TMY to begin at midnight, and force indices to desired
   year. (:issue:`2139`, :pull:`2138`)
 * Restructured the pvlib/spectrum folder by breaking up the contents of
   pvlib/spectrum/mismatch.py into pvlib/spectrum/mismatch.py,
   pvlib/spectrum/irradiance.py, and
   pvlib/spectrum/response.py. (:issue:`2125`, :pull:`2136`, :pull:`2151`)
 * Added function for calculating wind speed at different heights,
-  :py:func:`pvlib.atmosphere.windspeed_powerlaw`.
+  :py:func:`~pvlib.atmosphere.windspeed_powerlaw`.
   (:issue:`2118`, :pull:`2124`)
+* ``delta_t`` can now be specified with an array in the SPA functions.
+  The numba implementation now also allows calculation of ``delta_t``
+  internally.  (:issue:`2189`, :pull:`2190`)
 * The multithreaded SPA functions no longer emit a warning when calculating
   solar positions for short time series. (:pull:`2170`)
-* Implemented closed-form solution for alpha in :py:func:`pvlib.clearsky.detect_clearsky`, 
-  obviating the call to scipy.optimize that was prone to runtime errors and minimizing
+* Implemented closed-form solution for alpha in :py:func:`~pvlib.clearsky.detect_clearsky`, 
+  obviating the call to scipy.optimize, which was prone to runtime errors, and minimizing
   computation. (:issue:`2171`, :issue:`2216`, :pull:`2217`).
 
-
 Bug fixes
 ~~~~~~~~~
 * To prevent simulation output from differing slightly based on the time zone
@@ -58,27 +56,27 @@ Testing
 * Updated the tests for :py:func:`~pvlib.iotools.get_pvgis_tmy`
   and :py:func:`~pvlib.iotools.read_pvgis_tmy` as the default
   API endpoint has changed from 5.1 to 5.2. (:pull:`2222`)
-
+* Removed unused ``times`` input from ``dni_et`` fixture. (:issue:`2105`, :pull:`2156`)
 
 Documentation
 ~~~~~~~~~~~~~
-* Added gallery example demonstrating the application of
-  several spectral mismatch factor models.
-  (:issue:`2107`, :pull:`2114`)
-* Added gallery example demonstrating the application of
-  :py:func:`~pvlib.spectrum.average_photon_energy`. (:issue:`2194`, :pull:`2206`)
-* Added gallery example on calculating cell temperature for
-  floating PV. (:pull:`2110`)
-* Added gallery example demonstrating how to use
-  different Perez coefficients in a ModelChain.
-  (:issue:`2127`, :pull:`2148`)
-* Fixed examples in :py:func:`pvlib.shading.shaded_fraction1d`. (:pull:`#2215`)
-
-* Removed unused "times" input from dni_et() function (:issue:`2105`)
-* Updated :py:func:`pvlib.irradiance.haydavies` to include equation variable
-  definitions and a new "notes" section (:issue:`2183`, :pull:`2191`)
+* Added new gallery example pages for:
+  
+  - Demonstrating the application of several spectral mismatch factor models.
+    (:issue:`2107`, :pull:`2114`)
+  - Demonstrating the application of :py:func:`~pvlib.spectrum.average_photon_energy`.
+    (:issue:`2194`, :pull:`2206`)
+  - Calculating cell temperature for floating PV. (:pull:`2110`)
+  - Demonstrating how to use different Perez coefficients in a ModelChain.
+    (:issue:`2127`, :pull:`2148`)
 
-* Split the contributing page into several pages (:issue:`2210`, :pull:`2219`)
+* Fixed examples in :py:func:`~pvlib.shading.shaded_fraction1d`. (:pull:`2215`)
+* Updated model description, added equation variable definitions, and created a 
+  new "notes" section in :py:func:`~pvlib.irradiance.haydavies` and
+  :py:func:`~pvlib.irradiance.klucher`. (:issue:`2183`, :pull:`2191`,
+  :pull:`2192`)
+* Document units with Wm⁻² instead of W/m^2 throughout ``pvlib.irradiance``. (:issue:`2205`, :pull:`2191`)
+* Split the contributing page into several pages. (:issue:`2210`, :pull:`2219`)
 
 Requirements
 ~~~~~~~~~~~~
@@ -92,15 +90,23 @@ Contributors
 * Chris Deline (:ghuser:`cdeline`)
 * Ioannis Sifnaios (:ghuser:`IoannisSifnaios`)
 * Leonardo Micheli (:ghuser:`lmicheli`)
-* Echedey Luis (:ghuser:`echedey-ls`)
 * Rajiv Daxini (:ghuser:`RDaxini`)
 * Mark A. Mikofski (:ghuser:`mikofski`)
 * Ben Pierce (:ghuser:`bgpierc`)
 * Jose Meza (:ghuser:`JoseMezaMendieta`)
+* Kevin Anderson (:ghuser:`kandersolar`)
 * Luiz Reis (:ghuser:`luizreiscver`)
 * Carlos Cárdenas-Bravo (:ghuser:`cardenca`)
 * Marcos R. Escudero (:ghuser:`marc-resc`)
 * Bernat Nicolau (:ghuser:`BernatNicolau`)
 * Eduardo Sarquis (:ghuser:`EduardoSarquis`)
 * Adam R. Jensen (:ghuser:`AdamRJensen`)
 * Andrew B Godbehere (:ghuser:`agodbehere`)
+* Cliff Hansen (:ghuser:`cwhanse`)
+* Anton Driesse (:ghuser:`adriesse`)
+* Miguel Angel Sevillano Bendezú (:ghuser:`msevillanob`)
+* Erfan (:ghuser:`Metal-Bat`)
+* Will Holmgren (:ghuser:`wholmgren`)
+* Kurt Rhee (:ghuser:`kurt-rhee`)
+* :ghuser:`PhilBrk8`
+* Mark Campanelli (:ghuser:`markcampanelli`)

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

@@ -0,0 +1,32 @@
+.. _whatsnew_01120:
+
+
+v0.11.2 (Anticipated December, 2024)
+------------------------------------
+
+Deprecations
+~~~~~~~~~~~~
+
+
+Enhancements
+~~~~~~~~~~~~
+
+
+Documentation
+~~~~~~~~~~~~~
+* Edited docstrings for :py:func:`~pvlib.pvsystem.dc_ohms_from_percent` and
+  :py:func:`~pvlib.pvsystem.dc_ohmic_loss` for clarity. (:issue:`1601`, :pull:`2229`)
+
+
+Testing
+~~~~~~~
+
+
+Requirements
+~~~~~~~~~~~~
+
+
+Contributors
+~~~~~~~~~~~~
+* Cliff Hansen (:ghuser:`cwhanse`)
+

pvlib/irradiance.py

@@ -630,66 +630,74 @@ def klucher(surface_tilt, surface_azimuth, dhi, ghi, solar_zenith,
             solar_azimuth):
     r'''
     Determine diffuse irradiance from the sky on a tilted surface
-    using Klucher's 1979 model
-
-    .. math::
-
-       I_{d} = DHI \frac{1 + \cos\beta}{2} (1 + F' \sin^3(\beta/2))
-       (1 + F' \cos^2\theta\sin^3\theta_z)
-
-    where
-
-    .. math::
-
-       F' = 1 - (I_{d0} / GHI)^2
-
-    Klucher's 1979 model determines the diffuse irradiance from the sky
-    (ground reflected irradiance is not included in this algorithm) on a
-    tilted surface using the surface tilt angle, surface azimuth angle,
-    diffuse horizontal irradiance, direct normal irradiance, global
-    horizontal irradiance, extraterrestrial irradiance, sun zenith
-    angle, and sun azimuth angle.
+    using the Klucher (1979) model.
 
     Parameters
     ----------
     surface_tilt : numeric
-        Surface tilt angles in decimal degrees. surface_tilt must be >=0
+        Surface tilt angles in decimal degrees. ``surface_tilt`` must be >=0
         and <=180. The tilt angle is defined as degrees from horizontal
         (e.g. surface facing up = 0, surface facing horizon = 90)
 
     surface_azimuth : numeric
-        Surface azimuth angles in decimal degrees. surface_azimuth must
+        Surface azimuth angles in decimal degrees. ``surface_azimuth`` must
         be >=0 and <=360. The Azimuth convention is defined as degrees
         east of north (e.g. North = 0, South=180 East = 90, West = 270).
 
     dhi : numeric
-        Diffuse horizontal irradiance. [Wm⁻²] DHI must be >=0.
+        Diffuse horizontal irradiance, must be >=0. [Wm⁻²]
 
     ghi : numeric
-        Global irradiance. [Wm⁻²] DNI must be >=0.
+        Global horizontal irradiance, must be >=0. [Wm⁻²]
 
     solar_zenith : numeric
         Apparent (refraction-corrected) zenith angles in decimal
-        degrees. solar_zenith must be >=0 and <=180.
+        degrees. ``solar_zenith`` must be >=0 and <=180.
 
     solar_azimuth : numeric
-        Sun azimuth angles in decimal degrees. solar_azimuth must be >=0
+        Sun azimuth angles in decimal degrees. ``solar_azimuth`` must be >=0
         and <=360. The Azimuth convention is defined as degrees east of
         north (e.g. North = 0, East = 90, West = 270).
 
     Returns
     -------
     diffuse : numeric
-        The sky diffuse component of the solar radiation.
+        The sky diffuse component of the solar radiation. [Wm⁻²]
+
+    Notes
+    -----
+    The Klucher (1979) model  [1]_ [2]_ determines the diffuse irradiance
+    from the sky (ground reflected irradiance is not included in this
+    algorithm) on a tilted surface using the surface tilt angle, surface
+    azimuth angle, diffuse horizontal irradiance, global horizontal irradiance,
+    sun zenith angle, and sun azimuth angle. The expression for the sky diffuse
+    irradiance, :math:`I_d`, is as follows:
+
+    .. math::
+
+       I_{d} = DHI \frac{1 + \cos\beta}{2} (1 + F' \sin^3(\beta/2))
+       (1 + F' \cos^2\theta\sin^3\theta_z).
+
+    DHI is the diffuse horizontal irradiance, :math:`\beta` is the surface
+    tilt angle, :math:`\theta_z` is the solar zenith angle, and :math:`\theta`
+    is the angle of incidence. :math:`F'` is a modulating function to account
+    for when the sky changes from clear to overcast, and is defined as follows:
+
+    .. math::
+
+       F' = 1 - (DHI / GHI)^2,
+
+    where GHI is the global horiztonal irradiance.
 
     References
     ----------
-    .. [1] Loutzenhiser P.G. et. al. "Empirical validation of models to compute
-       solar irradiance on inclined surfaces for building energy simulation"
-       2007, Solar Energy vol. 81. pp. 254-267
-
-    .. [2] Klucher, T.M., 1979. Evaluation of models to predict insolation on
-       tilted surfaces. Solar Energy 23 (2), 111-114.
+    .. [1] Klucher, T. M. "Evaluation of models to predict insolation on
+       tilted surfaces" 1979, Solar Energy vol. 23 (2), pp. 111-114
+       :doi:`10.1016/0038-092X(79)90110-5`
+    .. [2] Loutzenhiser P. G. et al. "Empirical validation of models to
+       compute solar irradiance on inclined surfaces for building energy
+       simulation" 2007, Solar Energy vol. 81. pp. 254-267
+       :doi:`10.1016/j.solener.2006.03.009`
     '''
 
     # zenith angle with respect to panel normal.
@@ -721,7 +729,7 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
               return_components=False):
     r'''
     Determine diffuse irradiance from the sky on a tilted surface using the
-    Hay and Davies (1980) model [1]_ [2]_.
+    Hay and Davies (1980) model.
 
     The Hay and Davies model determines the diffuse irradiance from
     the sky (ground reflected irradiance is not included in this
@@ -790,8 +798,8 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
 
     Notes
     ------
-    In the Hay and Davies (1980) model, sky diffuse irradiance, :math:`I_d`,
-    is as follows:
+    In the Hay and Davies (1980) model  [1]_ [2]_, sky diffuse irradiance,
+    :math:`I_d`, is as follows:
 
     .. math::
             I_{d} = DHI \left( A\cdot R_b + (1 - A) \left(\frac{