From 55d50ab6948f43f59f7b9d0c5d406df358dbcea5 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Sat, 2 May 2026 15:05:07 -0700 Subject: [PATCH 1/8] edit docstring to clarify linke turbidity --- pvlib/clearsky.py | 41 +++++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/pvlib/clearsky.py b/pvlib/clearsky.py index 66b732e328..9d1a5b6b7b 100644 --- a/pvlib/clearsky.py +++ b/pvlib/clearsky.py @@ -19,46 +19,46 @@ def ineichen(apparent_zenith, airmass_absolute, linke_turbidity, altitude=0, dni_extra=1364., perez_enhancement=False): ''' - Determine clear sky GHI, DNI, and DHI from Ineichen/Perez model. + Determine clear-sky GHI, DNI, and DHI using the Ineichen/Perez model. - Implements the Ineichen and Perez clear sky model for global - horizontal irradiance (GHI), direct normal irradiance (DNI), and - calculates the clear-sky diffuse horizontal (DHI) component as the - difference between GHI and DNI*cos(zenith) as presented in [1]_ [2]_. A - report on clear sky models found the Ineichen/Perez model to have + The Ineichen and Perez clear sky model [1]_ [2]_ describes global + horizontal irradiance (GHI) and direct normal irradiance (DNI), Diffuse + horizontal irradiance (DHI) is then computed as DHI = GHI - DNI*cos(zenith) + Analysis of clear sky models found the Ineichen/Perez model to have excellent performance with a minimal input data set [3]_. - Default values for monthly Linke turbidity provided by SoDa [4]_, [5]_. + The Ineichen/Perez model requires Linke turbidity as input. Monthly + averages of gridded Linke turbidity (historical data from SoDa [4]_, [5]_) + are available using :py:func:`~pvlib.clearsky.lookup_linke_turbidity`. Parameters ----------- apparent_zenith : numeric - Refraction corrected solar zenith angle in degrees. + Refraction-corrected solar zenith angle. [°] airmass_absolute : numeric - Pressure corrected airmass. + Pressure-corrected airmass. [unitless] linke_turbidity : numeric - Linke Turbidity. + Linke turbidity. [unitless] altitude : numeric, default 0 - Altitude above sea level in meters. + Altitude above sea level. [m] - dni_extra : numeric, default 1364 - Extraterrestrial irradiance. The units of ``dni_extra`` - determine the units of the output. + dni_extra : numeric, default 1364 Wm⁻² + Extraterrestrial irradiance. perez_enhancement : bool, default False - Controls if the Perez enhancement factor should be applied. - Setting to True may produce spurious results for times when + If `True`, the Perez enhancement factor is applied. + The Perez enhancement factor may produce spurious results when the Sun is near the horizon and the airmass is high. See https://github.com/pvlib/pvlib-python/issues/435 Returns ------- clearsky : DataFrame (if Series input) or OrderedDict of arrays - DataFrame/OrderedDict contains the columns/keys - ``'dhi', 'dni', 'ghi'``. + Contains the columns/keys ``'dhi', 'dni', 'ghi'``, with the same + unit as the input parameter ``dni_extra``. See also -------- @@ -84,6 +84,11 @@ def ineichen(apparent_zenith, airmass_absolute, linke_turbidity, .. [5] J. Remund, et. al., "Worldwide Linke Turbidity Information", Proc. ISES Solar World Congress, June 2003. Goteborg, Sweden. + + Examples + -------- + https://pvlib-python.readthedocs.io/en/stable/user_guide/modeling_topics/clearsky.html#examples + ''' # noqa: E501 # ghi is calculated using either the equations in [1] by setting From c6b93be0951980ac2bf97b132ee184734d333282 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Sat, 2 May 2026 15:18:07 -0700 Subject: [PATCH 2/8] whatsnew --- docs/sphinx/source/whatsnew/v0.15.2.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/source/whatsnew/v0.15.2.rst b/docs/sphinx/source/whatsnew/v0.15.2.rst index 0f32b734ef..cf28a1105d 100644 --- a/docs/sphinx/source/whatsnew/v0.15.2.rst +++ b/docs/sphinx/source/whatsnew/v0.15.2.rst @@ -22,9 +22,12 @@ Enhancements Documentation ~~~~~~~~~~~~~ -* Clarified that :py:func:`pvlib.soiling.hsu` has an implicit minimum +* Clarifies that :py:func:`pvlib.soiling.hsu` has an implicit minimum soiling ratio of approximately 0.6563 due to the mathematical form of the model. (:issue:`2534`, :pull:`2743`) +* Clarifies how Linke turbidity values can be provided to + :py:func:`pvlib.clearsky.ineichen` via + :py:func:`pvlib.clearsky.lookup_linke_turbidity` (:issue:`2598`, :pull:`2746`) Testing From 30487f9fc54c586704f9b4424cc73f9fac2b9abe Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Sun, 3 May 2026 06:25:32 -0700 Subject: [PATCH 3/8] Update pvlib/clearsky.py Co-authored-by: Anton Driesse --- pvlib/clearsky.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pvlib/clearsky.py b/pvlib/clearsky.py index 9d1a5b6b7b..55ce08ea24 100644 --- a/pvlib/clearsky.py +++ b/pvlib/clearsky.py @@ -22,7 +22,7 @@ def ineichen(apparent_zenith, airmass_absolute, linke_turbidity, Determine clear-sky GHI, DNI, and DHI using the Ineichen/Perez model. The Ineichen and Perez clear sky model [1]_ [2]_ describes global - horizontal irradiance (GHI) and direct normal irradiance (DNI), Diffuse + horizontal irradiance (GHI) and direct normal irradiance (DNI). Diffuse horizontal irradiance (DHI) is then computed as DHI = GHI - DNI*cos(zenith) Analysis of clear sky models found the Ineichen/Perez model to have excellent performance with a minimal input data set [3]_. From 87856a03dacb04334c037c57866b4ce44340764c Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Sun, 3 May 2026 06:25:40 -0700 Subject: [PATCH 4/8] Update pvlib/clearsky.py Co-authored-by: Anton Driesse --- pvlib/clearsky.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pvlib/clearsky.py b/pvlib/clearsky.py index 55ce08ea24..8b43c96f93 100644 --- a/pvlib/clearsky.py +++ b/pvlib/clearsky.py @@ -21,7 +21,7 @@ def ineichen(apparent_zenith, airmass_absolute, linke_turbidity, ''' Determine clear-sky GHI, DNI, and DHI using the Ineichen/Perez model. - The Ineichen and Perez clear sky model [1]_ [2]_ describes global + The Ineichen and Perez clear sky model [1]_ [2]_ estimates global horizontal irradiance (GHI) and direct normal irradiance (DNI). Diffuse horizontal irradiance (DHI) is then computed as DHI = GHI - DNI*cos(zenith) Analysis of clear sky models found the Ineichen/Perez model to have From 07dbd3bf8302d5683b444597b227f65e98433293 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Sun, 3 May 2026 08:58:44 -0700 Subject: [PATCH 5/8] Update pvlib/clearsky.py Co-authored-by: Echedey Luis <80125792+echedey-ls@users.noreply.github.com> --- pvlib/clearsky.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pvlib/clearsky.py b/pvlib/clearsky.py index 8b43c96f93..f702ea96a4 100644 --- a/pvlib/clearsky.py +++ b/pvlib/clearsky.py @@ -49,7 +49,7 @@ def ineichen(apparent_zenith, airmass_absolute, linke_turbidity, Extraterrestrial irradiance. perez_enhancement : bool, default False - If `True`, the Perez enhancement factor is applied. + If ``True``, the Perez enhancement factor is applied. The Perez enhancement factor may produce spurious results when the Sun is near the horizon and the airmass is high. See https://github.com/pvlib/pvlib-python/issues/435 From a96557f3d2cdf4a0f265ac0bfe77b3aba4e21127 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Sun, 3 May 2026 14:03:01 -0700 Subject: [PATCH 6/8] add internal reference --- docs/sphinx/source/user_guide/modeling_topics/clearsky.rst | 2 +- pvlib/clearsky.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/source/user_guide/modeling_topics/clearsky.rst b/docs/sphinx/source/user_guide/modeling_topics/clearsky.rst index f074f21c99..635d1f3c25 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/clearsky.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/clearsky.rst @@ -256,6 +256,7 @@ wavelengths [Bir80]_, and is implemented in In [1]: plt.tight_layout() +.. _clearsky-examples: Examples ^^^^^^^^ @@ -281,7 +282,6 @@ A clear sky time series using only basic pvlib functions. In [1]: dni_extra = pvlib.irradiance.get_extra_radiation(times) - # an input is a pandas Series, so solis is a DataFrame In [1]: ineichen = clearsky.ineichen(apparent_zenith, airmass, linke_turbidity, altitude, dni_extra) In [1]: plt.figure(); diff --git a/pvlib/clearsky.py b/pvlib/clearsky.py index 9d1a5b6b7b..5ff16d9813 100644 --- a/pvlib/clearsky.py +++ b/pvlib/clearsky.py @@ -87,7 +87,7 @@ def ineichen(apparent_zenith, airmass_absolute, linke_turbidity, Examples -------- - https://pvlib-python.readthedocs.io/en/stable/user_guide/modeling_topics/clearsky.html#examples + See :ref:`Clearsky modeling examples ` ''' # noqa: E501 From ea45ac0d1560a1c961fabf5bab77bed9f532e74a Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Sun, 3 May 2026 16:02:48 -0700 Subject: [PATCH 7/8] blank line --- docs/sphinx/source/user_guide/modeling_topics/clearsky.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/sphinx/source/user_guide/modeling_topics/clearsky.rst b/docs/sphinx/source/user_guide/modeling_topics/clearsky.rst index 635d1f3c25..5aecd3f558 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/clearsky.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/clearsky.rst @@ -257,6 +257,7 @@ wavelengths [Bir80]_, and is implemented in .. _clearsky-examples: + Examples ^^^^^^^^ From 9e41c8108128e6a5619b7dcef43b5ff64fca1ea0 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Sun, 3 May 2026 16:27:17 -0700 Subject: [PATCH 8/8] move down a few lines --- docs/sphinx/source/user_guide/modeling_topics/clearsky.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/source/user_guide/modeling_topics/clearsky.rst b/docs/sphinx/source/user_guide/modeling_topics/clearsky.rst index 5aecd3f558..cde1c3c58c 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/clearsky.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/clearsky.rst @@ -255,12 +255,11 @@ wavelengths [Bir80]_, and is implemented in @savefig kasten-tl.png width=10in In [1]: plt.tight_layout() - -.. _clearsky-examples: - Examples ^^^^^^^^ +.. _clearsky-examples: + A clear sky time series using only basic pvlib functions. .. ipython::