Skip to content

Standardize diffuse irradiance component names and descriptions in docstrings #2827

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

Open
cbcrespo wants to merge 2 commits into
base: main
Choose a base branch
from
+74 −57
Open

Standardize diffuse irradiance component names and descriptions in docstrings #2827

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d65bcc8
Standardize component names and descriptions
cbcrespo Jul 17, 2026
f6fe69f
Add whatsnew entry
cbcrespo Jul 17, 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
2 changes: 2 additions & 0 deletions docs/sphinx/source/whatsnew/v0.15.3.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ Documentation
* Fix broken link in GitHub Contributing tab. (:issue:`2628`, :pull:`2806`)
* Fixed broken ``interval`` keyword argument in the ``oedi_9068`` gallery
example; the correct parameter name is ``time_step``. (:issue:`2791`)
* Standardized diffuse component names and descriptions in the docstrings of
multiple functions in :py:mod:`pvlib.irradiance`. (:pull:`2827`)


Testing
Expand Down
125 changes: 70 additions & 55 deletions pvlib/irradiance.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -566,8 +566,8 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None):

Returns
-------
grounddiffuse : numeric
Ground reflected irradiance. [Wm⁻²]
poa_ground_diffuse : numeric
The ground diffuse component of irradiance on a tilted plane. [Wm⁻²]

Notes
-----
Expand All @@ -589,14 +589,17 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None):
if surface_type is not None:
albedo = pvlib.albedo.SURFACE_ALBEDOS[surface_type]

diffuse_irrad = ghi * albedo * (1 - np.cos(np.radians(surface_tilt))) * 0.5
poa_ground_diffuse = (
ghi * albedo *
(1 - np.cos(np.radians(surface_tilt))) * 0.5
)

try:
diffuse_irrad.name = 'diffuse_ground'
poa_ground_diffuse.name = 'poa_ground_diffuse'
except AttributeError:
pass

return diffuse_irrad
return poa_ground_diffuse


def isotropic(surface_tilt, dhi):
Expand Down Expand Up @@ -673,8 +676,8 @@ def klucher(surface_tilt, surface_azimuth, dhi, ghi, solar_zenith,

Returns
-------
diffuse : numeric
The sky diffuse component of the solar radiation. [Wm⁻²]
poa_sky_diffuse : numeric
The sky diffuse component of irradiance on a tilted plane. [Wm⁻²]

Notes
-----
Expand All @@ -699,7 +702,7 @@ def klucher(surface_tilt, surface_azimuth, dhi, ghi, solar_zenith,

F' = 1 - (DHI / GHI)^2,

where GHI is the global horiztonal irradiance.
where GHI is the global horizontal irradiance.

References
----------
Expand Down Expand Up @@ -731,9 +734,9 @@ def klucher(surface_tilt, surface_azimuth, dhi, ghi, solar_zenith,
term2 = 1 + F * (tools.sind(0.5 * surface_tilt) ** 3)
term3 = 1 + F * (cos_tt ** 2) * (tools.sind(solar_zenith) ** 3)

sky_diffuse = dhi * term1 * term2 * term3
poa_sky_diffuse = dhi * term1 * term2 * term3

return sky_diffuse
return poa_sky_diffuse


def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
Expand Down Expand Up @@ -782,25 +785,28 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
or supply ``projection_ratio``.

return_components : bool, default `False`
If `False`, ``sky_diffuse`` is returned.
If `False`, ``poa_sky_diffuse`` is returned.
If `True`, ``diffuse_components`` is returned.

Returns
--------
numeric, dict, or DataFrame
Return type controlled by ``return_components`` argument.
If `False`, ``sky_diffuse`` is returned.
If `False`, ``poa_sky_diffuse`` is returned.
If `True`, ``diffuse_components`` is returned.

sky_diffuse : numeric
The sky diffuse component of the solar radiation on a tilted
surface. [Wm⁻²]
poa_sky_diffuse : numeric
The sky diffuse component of irradiance on a tilted plane. [Wm⁻²]

diffuse_components : dict (array input) or DataFrame (Series input)
Keys/columns are:
* poa_sky_diffuse: Total sky diffuse
* poa_isotropic
* poa_circumsolar
* poa_sky_diffuse: The sky diffuse component of irradiance on a
tilted plane. [Wm⁻²]
* poa_isotropic: The portion of sky diffuse irradiance on a tilted
plane from the isotropic sky dome. [Wm⁻²]
* poa_circumsolar: The portion of sky diffuse irradiance on a
tilted plane from the circumsolar region. [Wm⁻²]


Notes
------
Expand Down Expand Up @@ -855,20 +861,20 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,

poa_isotropic = np.maximum(dhi * term1 * term2, 0)
poa_circumsolar = np.maximum(dhi * (AI * Rb), 0)
sky_diffuse = poa_isotropic + poa_circumsolar
poa_sky_diffuse = poa_isotropic + poa_circumsolar

if return_components:
diffuse_components = {
'poa_sky_diffuse': sky_diffuse,
'poa_sky_diffuse': poa_sky_diffuse,
'poa_isotropic': poa_isotropic,
'poa_circumsolar': poa_circumsolar
}

if isinstance(sky_diffuse, pd.Series):
if isinstance(poa_sky_diffuse, pd.Series):
diffuse_components = pd.DataFrame(diffuse_components)
return diffuse_components
else:
return sky_diffuse
return poa_sky_diffuse


def reindl(surface_tilt, surface_azimuth, dhi, dni, ghi, dni_extra,
Expand Down Expand Up @@ -1016,15 +1022,17 @@ def king(surface_tilt, dhi, ghi, solar_zenith):
Returns
--------
poa_sky_diffuse : numeric
The diffuse component of the solar radiation.
The sky diffuse component of irradiance on a tilted plane. [Wm⁻²]
'''

sky_diffuse = (dhi * (1 + tools.cosd(surface_tilt)) / 2 + ghi *
(0.012 * solar_zenith - 0.04) *
(1 - tools.cosd(surface_tilt)) / 2)
sky_diffuse = np.maximum(sky_diffuse, 0)
poa_sky_diffuse = (
dhi * (1 + tools.cosd(surface_tilt)) / 2 + ghi *
(0.012 * solar_zenith - 0.04) *
(1 - tools.cosd(surface_tilt)) / 2
)
poa_sky_diffuse = np.maximum(poa_sky_diffuse, 0)

return sky_diffuse
return poa_sky_diffuse


def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
Expand Down Expand Up @@ -1106,19 +1114,23 @@ def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
--------
numeric, dict, or DataFrame
Return type controlled by `return_components` argument.
If ``return_components=False``, `sky_diffuse` is returned.
If ``return_components=False``, `poa_sky_diffuse` is returned.
If ``return_components=True``, `diffuse_components` is returned.

sky_diffuse : numeric
poa_sky_diffuse : numeric
The sky diffuse component of the solar radiation on a tilted
surface.

diffuse_components : dict (array input) or DataFrame (Series input)
Keys/columns are:
* poa_sky_diffuse: Total sky diffuse
* poa_isotropic
* poa_circumsolar
* poa_horizon
* poa_sky_diffuse: The sky diffuse component of irradiance on a
tilted plane. [Wm⁻²]
* poa_isotropic: The portion of sky diffuse irradiance on a tilted
plane from the isotropic sky dome. [Wm⁻²]
* poa_circumsolar: The portion of sky diffuse irradiance on a
tilted plane from the circumsolar region. [Wm⁻²]
* poa_horizon: The portion of sky diffuse irradiance on a tilted
plane from the horizon. [Wm⁻²]


References
Expand Down Expand Up @@ -1191,33 +1203,33 @@ def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
term2 = F1 * A / B
term3 = F2 * tools.sind(surface_tilt)

sky_diffuse = np.maximum(dhi * (term1 + term2 + term3), 0)
poa_sky_diffuse = np.maximum(dhi * (term1 + term2 + term3), 0)

# we've preserved the input type until now, so don't ruin it!
if isinstance(sky_diffuse, pd.Series):
sky_diffuse[np.isnan(airmass)] = 0
if isinstance(poa_sky_diffuse, pd.Series):
poa_sky_diffuse[np.isnan(airmass)] = 0
else:
sky_diffuse = np.where(np.isnan(airmass), 0, sky_diffuse)
poa_sky_diffuse = np.where(np.isnan(airmass), 0, poa_sky_diffuse)

if return_components:
diffuse_components = {
'poa_sky_diffuse': sky_diffuse,
'poa_sky_diffuse': poa_sky_diffuse,
'poa_isotropic': dhi * term1,
'poa_circumsolar': dhi * term2,
'poa_horizon': dhi * term3
}

# Set values of components to 0 when sky_diffuse is 0
mask = sky_diffuse == 0
if isinstance(sky_diffuse, pd.Series):
# Set values of components to 0 when poa_sky_diffuse is 0
mask = poa_sky_diffuse == 0
if isinstance(poa_sky_diffuse, pd.Series):
diffuse_components = pd.DataFrame(diffuse_components)
diffuse_components.loc[mask] = 0
else:
diffuse_components = {k: np.where(mask, 0, v) for k, v in
diffuse_components.items()}
return diffuse_components
else:
return sky_diffuse
return poa_sky_diffuse


def _calc_delta(dhi, dni_extra, solar_zenith, airmass=None):
Expand Down Expand Up @@ -1347,19 +1359,22 @@ def perez_driesse(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
--------
numeric, dict, or DataFrame
Return type controlled by `return_components` argument.
If ``return_components=False``, `sky_diffuse` is returned.
If ``return_components=False``, `poa_sky_diffuse` is returned.
If ``return_components=True``, `diffuse_components` is returned.

sky_diffuse : numeric
The sky diffuse component of the solar radiation on a tilted
surface.
poa_sky_diffuse : numeric
The sky diffuse component of irradiance on a tilted plane. [Wm⁻²]

diffuse_components : dict (array input) or DataFrame (Series input)
Keys/columns are:
* poa_sky_diffuse: Total sky diffuse
* poa_isotropic
* poa_circumsolar
* poa_horizon
* poa_sky_diffuse: The sky diffuse component of irradiance on a
tilted plane. [Wm⁻²]
* poa_isotropic: The portion of sky diffuse irradiance on a
tilted plane from the isotropic sky dome. [Wm⁻²]
* poa_circumsolar: The portion of sky diffuse irradiance on a
tilted plane from the circumsolar region. [Wm⁻²]
* poa_horizon: The portion of sky diffuse irradiance on a tilted
plane from the horizon. [Wm⁻²]

Notes
-----
Expand Down Expand Up @@ -1416,22 +1431,22 @@ def perez_driesse(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
term2 = F1 * A / B
term3 = F2 * tools.sind(surface_tilt)

sky_diffuse = np.maximum(dhi * (term1 + term2 + term3), 0)
poa_sky_diffuse = np.maximum(dhi * (term1 + term2 + term3), 0)

if return_components:
diffuse_components = {
'poa_sky_diffuse': sky_diffuse,
'poa_sky_diffuse': poa_sky_diffuse,
'poa_isotropic': dhi * term1,
'poa_circumsolar': dhi * term2,
'poa_horizon': dhi * term3
}

if isinstance(sky_diffuse, pd.Series):
if isinstance(poa_sky_diffuse, pd.Series):
diffuse_components = pd.DataFrame(diffuse_components)

return diffuse_components
else:
return sky_diffuse
return poa_sky_diffuse


def _poa_from_ghi(surface_tilt, surface_azimuth,
Expand Down
4 changes: 2 additions & 2 deletions tests/test_irradiance.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ def test_get_ground_diffuse_simple_float():

def test_get_ground_diffuse_simple_series(irrad_data):
ground_irrad = irradiance.get_ground_diffuse(40, irrad_data['ghi'])
assert ground_irrad.name == 'diffuse_ground'
assert ground_irrad.name == 'poa_ground_diffuse'


def test_get_ground_diffuse_albedo_0(irrad_data):
Expand All @@ -142,7 +142,7 @@ def test_get_ground_diffuse_albedo_series(times):
ground_irrad = irradiance.get_ground_diffuse(
45, pd.Series(1000, index=times), albedo)
expected = albedo * 0.5 * (1 - np.sqrt(2) / 2.) * 1000
expected.name = 'diffuse_ground'
expected.name = 'poa_ground_diffuse'
assert_series_equal(ground_irrad, expected)


Expand Down
Loading