Adds k parameter to temperature.ross #2521

ramaroesilva · 2025-07-31T09:06:16Z

Closes pvlib.temperature.ross could accept ross parameter as a NOCT alternative #2506
I am familiar with the contributing guidelines
Tests added
Updates entries in docs/sphinx/source/reference for API changes.
Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for all changes. Includes link to the GitHub Issue with :issue:`num` or this Pull Request with :pull:`num`. Includes contributor name and/or GitHub username (link with :ghuser:`user`).
New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
Pull request is nearly complete and ready for detailed review.
Maintainer: Appropriate GitHub Labels (including remote-data) and Milestone are assigned to the Pull Request and linked Issue.

I think the issue is clear enough.

ramaroesilva · 2025-07-31T09:11:54Z

In #2506 @cwhanse mentions that it is difficult to find the 1981 paper from Ross, to which @kandersolar provided a wayback machine url. Should I add it to the documentation of temperature.ross? If so, how?

RDaxini

Thanks for your contribution @ramaroesilva
I added a few suggestions for formatting the docstring and references. Have a look, and if you look under the "files changed" tab you can "add suggestion to batch" and implement more than one suggestion in a single commit

pvlib/temperature.py

RDaxini · 2025-07-31T16:21:05Z

pvlib/temperature.py

@@ -638,6 +638,9 @@ def ross(poa_global, temp_air, noct):
    noct : numeric
        Nominal operating cell temperature [C], determined at conditions of
        800 W/m^2 irradiance, 20 C ambient air temperature and 1 m/s wind.
+    k: numeric
+        Ross coefficient [Km^2/W], which is an alternative to employing


Suggested change

Ross coefficient [Km^2/W], which is an alternative to employing

Ross coefficient [Km²W⁻¹], which is an alternative to employing

Last comment for me: We should mark both noct and k as optional. I can't suggest for a line that isn't being modified, but it would be like this:

noct: numeric, optional Nominal operating cell temperature [C], determined at conditions of 800 W/m^2 irradiance, 20 C ambient air temperature and 1 m/s wind. If ``noct`` is not provided, ``k`` is required.

And similar for k

The double ticks "``" format the enclosed string as a parameter.

RDaxini · 2025-07-31T16:28:32Z

pvlib/temperature.py

    where :math:`S` is the plane of array irradiance in :math:`mW/{cm}^2`.
    This function expects irradiance in :math:`W/m^2`.


Let others comment, but I think Wm⁻² looks cleaner than the larger font bolt+italic math type for units. Might be worth saving that for variables(?)
At least if sticking with :math: then I think superscript would be better than a /: `:math:`mW{cm}^{-2}

Suggested change

where :math:`S` is the plane of array irradiance in :math:`mW/{cm}^2`.

This function expects irradiance in :math:`W/m^2`.

where :math:`S` is the plane of array irradiance in mWm⁻².

This function expects irradiance in Wm⁻².

RDaxini · 2025-07-31T16:30:18Z

pvlib/temperature.py

+       Energy, vol. 34, no. 1, pp. 23–29, Jan. 2009, doi:
+       https://doi.org/10.1016/j.renene.2008.04.009.


Use the sphinx doi role here to hyperlink the doi to the paper automatically

Suggested change

Energy, vol. 34, no. 1, pp. 23–29, Jan. 2009, doi:

https://doi.org/10.1016/j.renene.2008.04.009.

Energy, vol. 34, no. 1, pp. 23–29, Jan. 2009,

:doi:`10.1016/j.renene.2008.04.009`

RDaxini · 2025-07-31T16:35:35Z

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

+* Rename parameter name ``aparent_azimuth`` to ``solar_azimuth`` in :py:func:`~pvlib.tracking.singleaxis`.
+  (:issue:`2479`, :pull:`2480`)
+* Adds k coefficient in :py:func:`~pvlib.temperature.ross`
+  (:issue:`2506`, :pull:`2521`)
+


Adds --> Add for the whatsnew

Suggested change

* Rename parameter name ``aparent_azimuth`` to ``solar_azimuth`` in :py:func:`~pvlib.tracking.singleaxis`.

(:issue:`2479`, :pull:`2480`)

* Adds k coefficient in :py:func:`~pvlib.temperature.ross`

(:issue:`2506`, :pull:`2521`)

* Rename parameter name ``aparent_azimuth`` to ``solar_azimuth`` in :py:func:`~pvlib.tracking.singleaxis`.

(:issue:`2479`, :pull:`2480`)

* Add k coefficient in :py:func:`~pvlib.temperature.ross`

(:issue:`2506`, :pull:`2521`)

cwhanse · 2025-07-31T18:10:55Z

pvlib/temperature.py


    where :math:`S` is the plane of array irradiance in :math:`mW/{cm}^2`.
    This function expects irradiance in :math:`W/m^2`.

+    Reference values for k are provided in [2]_, covering different types


Suggested change

Reference values for k are provided in [2]_, covering different types

Representative values for k are provided in [2]_, covering different types

Added this in latest commit, thanks!

cwhanse · 2025-07-31T18:12:27Z

pvlib/temperature.py

+    +---------------------+-----------+
+    | Mounting            | :math:`k` |
+    +=====================+===========+
+    | well_cooled         | 0.02      |


Completely optional: you could replace the underscore with a space, because pvlib isn't providing these values in a dict with e.g. well_cooled as a key value.

Followed your suggestion in latest commit, thanks!

cwhanse · 2025-07-31T18:13:06Z

pvlib/temperature.py

-    # factor of 0.1 converts irradiance from W/m2 to mW/cm2
-    return temp_air + (noct - 20.) / 80. * poa_global * 0.1
+    if (noct is None) & (k is None):
+        raise ValueError("noct or k need to be provided as numeric input.")


Suggested change

raise ValueError("noct or k need to be provided as numeric input.")

raise ValueError("Either noct or k is required.")

Do these new warnings need to be tested?

@cwhanse added this in latest commit, thanks!

@RDaxini I did some light testing on my local dev repository (providing one of the two variables and both). Do you need me to do something more specific?

Let me know if you need me to do something more to advance this PR :-)

cwhanse · 2025-07-31T18:13:18Z

pvlib/temperature.py

+    if (noct is None) & (k is None):
+        raise ValueError("noct or k need to be provided as numeric input.")
+    elif (noct is not None) & (k is not None):
+        raise ValueError("Provide only noct or k, not both.")


Suggested change

raise ValueError("Provide only noct or k, not both.")

raise ValueError("Provide only one of noct or k, not both.")

Added this in latest commit, thanks!

pvlib/temperature.py

cwhanse · 2025-08-01T14:55:25Z

@ramaroesilva if you can fix the merge conflicts in the whatsnew file, we can launch the CI. To fix the conflicts, just keep both sets of lines - this sometimes happens when two PRs are adding lines at the same position.

ramaroesilva · 2025-08-01T15:27:28Z

@ramaroesilva if you can fix the merge conflicts in the whatsnew file, we can launch the CI. To fix the conflicts, just keep both sets of lines - this sometimes happens when two PRs are adding lines at the same position.

@cwhanse merge conflict fixed :-)

pvlib/temperature.py

cwhanse · 2025-08-01T16:21:33Z

tests/test_temperature.py

+
+    expected = expected.values
+    assert_allclose(expected, result1)
+    assert_allclose(expected, result2)


Add a test for the errors, to raise the code coverage.

Suggested change

assert_allclose(expected, result2)

assert_allclose(expected, result2)

def test_noct_sam_errors():

with pytest.raises(ValueError, match='Either noct or k need is required'):

temperature.ross(1000., 30.)

with pytest.raises(ValueError, match='Provide only one of noct or k'):

temperature.ross(1000., 30., noct=45., k=0.02)

cwhanse · 2025-08-01T17:16:58Z

You can ignore the test failure for py3.9

pvlib/temperature.py

cwhanse · 2025-08-15T16:38:02Z

pvlib/temperature.py

@@ -638,6 +638,9 @@ def ross(poa_global, temp_air, noct):
    noct : numeric
        Nominal operating cell temperature [C], determined at conditions of
        800 W/m^2 irradiance, 20 C ambient air temperature and 1 m/s wind.
+    k: numeric
+        Ross coefficient [Km^2/W], which is an alternative to employing


Last comment for me: We should mark both noct and k as optional. I can't suggest for a line that isn't being modified, but it would be like this:

noct: numeric, optional Nominal operating cell temperature [C], determined at conditions of 800 W/m^2 irradiance, 20 C ambient air temperature and 1 m/s wind. If ``noct`` is not provided, ``k`` is required.

And similar for k

The double ticks "``" format the enclosed string as a parameter.

ramaroesilva added 2 commits July 31, 2025 09:56

Adds k parameter to temperature.ross

85aa720

Updates whatsnew file for v13.1

50da75f

ramaroesilva mentioned this pull request Jul 31, 2025

Repair broken link in get_pvgis_hourly documentation #2517

Merged

8 tasks

kandersolar added the enhancement label Jul 31, 2025

kandersolar added this to the v0.13.1 milestone Jul 31, 2025

RDaxini reviewed Jul 31, 2025

View reviewed changes

ramaroesilva added 2 commits July 31, 2025 18:09

Corrects minor typos.

48866ee

Corrects doi formatting.

c917c61

cwhanse reviewed Jul 31, 2025

View reviewed changes

Improve docstring and initial test messages.

b3b10fc

cwhanse reviewed Jul 31, 2025

View reviewed changes

pvlib/temperature.py Show resolved Hide resolved

Adds tests for temperature.ross

70616e1

ramaroesilva and others added 5 commits August 1, 2025 15:56

Changes variables in test from int to float.

b71960b

Merge branch 'main' into ross-k

c3edec5

Addresses flake8 issues.

3d8db5e

Resolves conflict in whatsnew file.

3766673

Fixes flake8 issue.

058e1f0

RDaxini reviewed Aug 1, 2025

View reviewed changes

pvlib/temperature.py Show resolved Hide resolved

cwhanse reviewed Aug 1, 2025

View reviewed changes

Covers errors in testing temperature.ross

97535a0

cwhanse reviewed Aug 1, 2025

View reviewed changes

pvlib/temperature.py Show resolved Hide resolved

ramaroesilva added 2 commits August 1, 2025 22:05

Improves documentation on temperature.ross

0cc4b5f

Corrects minor typo.

fd72680

cwhanse approved these changes Aug 15, 2025

View reviewed changes

	Ross coefficient [Km^2/W], which is an alternative to employing
	Ross coefficient [Km²W⁻¹], which is an alternative to employing

		where :math:`S` is the plane of array irradiance in :math:`mW/{cm}^2`.
		This function expects irradiance in :math:`W/m^2`.

		Energy, vol. 34, no. 1, pp. 23–29, Jan. 2009, doi:
		https://doi.org/10.1016/j.renene.2008.04.009.

	Reference values for k are provided in [2]_, covering different types
	Representative values for k are provided in [2]_, covering different types

	raise ValueError("noct or k need to be provided as numeric input.")
	raise ValueError("Either noct or k is required.")

	raise ValueError("Provide only noct or k, not both.")
	raise ValueError("Provide only one of noct or k, not both.")

-    assert_allclose(expected, result2)
+    assert_allclose(expected, result2)
+def test_noct_sam_errors():
+    with pytest.raises(ValueError, match='Either noct or k need is required'):
+        temperature.ross(1000., 30.)
+    with pytest.raises(ValueError, match='Provide only one of noct or k'):
+        temperature.ross(1000., 30., noct=45., k=0.02)

Adds k parameter to temperature.ross #2521

Are you sure you want to change the base?

Adds k parameter to temperature.ross #2521

Uh oh!

Conversation

ramaroesilva commented Jul 31, 2025 • edited by kandersolar Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ramaroesilva commented Jul 31, 2025

Uh oh!

RDaxini left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cwhanse Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cwhanse commented Aug 1, 2025

Uh oh!

ramaroesilva commented Aug 1, 2025

Uh oh!

Uh oh!

cwhanse Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cwhanse commented Aug 1, 2025

Uh oh!

Uh oh!

cwhanse Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ramaroesilva commented Jul 31, 2025 •

edited by kandersolar

Loading

RDaxini left a comment •

edited

Loading

cwhanse Aug 15, 2025 •

edited

Loading

cwhanse Aug 1, 2025 •

edited

Loading

cwhanse Aug 15, 2025 •

edited

Loading