Skip to content

Clarify linke turbidity in docs for clearsky.ineichen #2746

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cwhanse merged 9 commits into from
May 4, 2026
Merged

Clarify linke turbidity in docs for clearsky.ineichen #2746

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
55d50ab
edit docstring to clarify linke turbidity
cwhanse May 2, 2026
c6b93be
whatsnew
cwhanse May 2, 2026
30487f9
Update pvlib/clearsky.py
cwhanse May 3, 2026
87856a0
Update pvlib/clearsky.py
cwhanse May 3, 2026
07dbd3b
Update pvlib/clearsky.py
cwhanse May 3, 2026
a96557f
add internal reference
cwhanse May 3, 2026
832247a
Merge branch 'linke_docs' of https://github.com/cwhanse/pvlib-python …
cwhanse May 3, 2026
ea45ac0
blank line
cwhanse May 3, 2026
9e41c81
move down a few lines
cwhanse May 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion docs/sphinx/source/whatsnew/v0.15.2.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
41 changes: 23 additions & 18 deletions pvlib/clearsky.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment thread
cwhanse marked this conversation as resolved.
Outdated
horizontal irradiance (GHI) and direct normal irradiance (DNI), Diffuse
Comment thread
cwhanse marked this conversation as resolved.
Outdated
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.
Comment thread
cwhanse marked this conversation as resolved.
Outdated
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
--------
Expand All @@ -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

@echedey-ls echedey-ls May 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we use an internal reference here?

@cwhanse cwhanse May 3, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do I do that?

@echedey-ls echedey-ls May 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In modeling_topics.rst, add something like

.. _clearsky-examples:

at line 258 before the subsection Examples title.

Then, in this section, cross-reference with

See :ref:`clearsky-examples`
or
See :ref:`Clearsky Modeling Topic examples <clearsky-examples>`

(text between <> is the reference, prior to it is text to show; if omitted, I think it would plainly output "clearsky-examples"

@cwhanse cwhanse May 3, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For me, the link doesn't appear where intended. Browser issue maybe?

@echedey-ls echedey-ls May 4, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean that the title appears hidden by top navbar and you have to scroll a little up?

Latest commit anchors the reference to the paragraph instead of to the header. I'm pretty sure you must have nailed it at commit ea45ac0; I seem unable to understand why that wouldn't work for you.

@cwhanse cwhanse May 4, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its more than a whole page off. If the PR view isn't where the view will appear after the PR is merged, then I'd say move ahead, merge, and then fix if needed.

@echedey-ls echedey-ls May 4, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm I wasn't able to reproduce that yesterday. I'm okay with a follow-up. LGTM.


''' # noqa: E501

# ghi is calculated using either the equations in [1] by setting
Expand Down
Loading