Clarify linke turbidity in docs for clearsky.ineichen (pvlib#2746)

* edit docstring to clarify linke turbidity

* whatsnew

* Update pvlib/clearsky.py

Co-authored-by: Anton Driesse <anton.driesse@pvperformancelabs.com>

* Update pvlib/clearsky.py

Co-authored-by: Anton Driesse <anton.driesse@pvperformancelabs.com>

* Update pvlib/clearsky.py

Co-authored-by: Echedey Luis <80125792+echedey-ls@users.noreply.github.com>

* add internal reference

* blank line

* move down a few lines

---------

Co-authored-by: Anton Driesse <anton.driesse@pvperformancelabs.com>
Co-authored-by: Echedey Luis <80125792+echedey-ls@users.noreply.github.com>

Author: 3 people

docs/sphinx/source/user_guide/modeling_topics/clearsky.rst

@@ -255,10 +255,11 @@ wavelengths [Bir80]_, and is implemented in
     @savefig kasten-tl.png width=10in
     In [1]: plt.tight_layout()
 
-
 Examples
 ^^^^^^^^
 
+.. _clearsky-examples:
+
 A clear sky time series using only basic pvlib functions.
 
 .. ipython::
@@ -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();

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

@@ -25,9 +25,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

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]_ 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
     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
+    --------
+    See :ref:`Clearsky modeling examples <clearsky-examples>`
+
     '''  # noqa: E501
 
     # ghi is calculated using either the equations in [1] by setting