Villalva Algorithm Pull Request by JFrederico2022 · Pull Request #2878 · pvlib/pvlib-python

JFrederico2022 · 2026-10-03T02:30:34Z

Closes #xxxx
I am familiar with the contributing guidelines
I attest that all AI-generated material has been vetted for accuracy and is in compliance with the pvlib license
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.

github-actions · 2026-10-03T02:30:43Z

Hey @JFrederico2022! 🎉

Thanks for opening your first pull request! We appreciate your
contribution. Please ensure you have reviewed and understood the
contributing guidelines.

If AI is used for any portion of this PR, you must vet the content
for technical accuracy.

Finally, be sure the PR description includes the PR
checklist,
and complete the items you are able to.

cwhanse · 2026-10-04T15:35:57Z

@JFrederico2022 pvlib should get only the functions, not the notebook. It has been a while since we discussed that: #2754 (comment) "In pvlib, a calcparams_villalva function would go into pvlib.pvsystem. Code for fitting would go into pvlib.ivtools.sdm in a new module villalva.py"

If you want, you can convert the notebook to a python script and add to the Example Gallery. Just start the script name with "plot_" and use docstrings where you want text to appear.

JFrederico2022 · 2026-10-06T19:03:57Z

Hello, @cwhanse

I updated the docs. Please, let me know if they are all right.

Best regards,
João Frederico

cwhanse · 2026-10-06T23:31:30Z

+    rows = []
+    rs_values = np.arange(0.0, rs_max + 0.5 * rs_step, rs_step)
+
+    for resistance_series in rs_values:


It looks to me that the helper function will operate on a vector rs_values. I think this for loop could go away. I'd set the numpy error state is set to ignore division by zero, then filter the output values to exclude NaN and negative parameters before finding the values at minimum power error.

cwhanse · 2026-10-06T23:32:59Z

+
+    References
+    ----------
+    .. [1] M. G. Villalva, PhD thesis, Chapter 3 and Appendix A.


Can we add a DOI for both of these references?

Sure! Here are the full references alongside their DOIs:

[1] M. G. Villalva, "Three-phase electronic power converter for a grid-connected photovoltaic system," PhD Thesis, Unicamp, 2010. DOI: 10.47749/T/UNICAMP.2010.781324

[2] M. G. Villalva, J. R. Gazoli, and E. Ruppert Filho, "Comprehensive Approach to Modeling and Simulation of Photovoltaic Arrays," IEEE Transactions on Power Electronics, 2009. DOI: 10.1109/TPEL.2009.2013862

Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

ramaroesilva · 2026-10-07T06:35:21Z

Hi @JFrederico2022, great initiative!

In my opinion, I think it would be nice for your PR to have a corresponding issue which includes a description of what you are adding to pvlib (e.g., what do you see is missing that a PR would add and include sources). That way reviewers and curious people can have a quick outlook of what's happening.

RDaxini · 2026-10-07T06:44:52Z

Hi @JFrederico2022, great initiative!

In my opinion, I think it would be nice for your PR to have a corresponding issue which includes a description of what you are adding to pvlib (e.g., what do you see is missing that a PR would add and include sources). That way reviewers and curious people can have a quick outlook of what's happening.

The issue exists (#2754) but, @JFrederico2022, please tag this in the PR template

echedey-ls · 2026-10-07T09:13:15Z

+    References
+    ----------
+    .. [1] M. G. Villalva, "Three-phase electronic power converter for a grid-connected photovoltaic system," 
+       PhD Thesis, Unicamp, 2010. DOI: 10.47749/T/UNICAMP.2010.781324


Suggested change

PhD Thesis, Unicamp, 2010. DOI: 10.47749/T/UNICAMP.2010.781324

PhD Thesis, Unicamp, 2010. :doi:`10.47749/T/UNICAMP.2010.781324`

Apply this DOI formatting to calcparams_villalba too.

echedey-ls · 2026-10-07T09:13:30Z

+       PhD Thesis, Unicamp, 2010. DOI: 10.47749/T/UNICAMP.2010.781324
+    .. [2] M. G. Villalva, J. R. Gazoli, and E. Ruppert Filho, 
+       "Comprehensive Approach to Modeling and Simulation of Photovoltaic Arrays," 
+       IEEE Transactions on Power Electronics, 2009. DOI: 10.1109/TPEL.2009.2013862


Suggested change

IEEE Transactions on Power Electronics, 2009. DOI: 10.1109/TPEL.2009.2013862

IEEE Transactions on Power Electronics, 2009. :doi:`10.1109/TPEL.2009.2013862`

Same as above.

echedey-ls · 2026-10-07T09:25:15Z

Remember to list the new functions in https://github.com/pvlib/pvlib-python/blob/main/docs/sphinx/source/reference/pv_modeling/sdm.rst?plain=1

RDaxini

I have suggested a few basic docstring revisions. You can implement changes recommended by reviewers either by committing them individually or, under the Files changed tab, adding the suggestions to a batch and committing them all at once.

Happy to look more in depth at the core implementation in the coming days

RDaxini · 2026-10-07T16:01:04Z

+    The dimensionless diode ideality factor :math:`n` is supplied by the user. The
+    modified ideality factor at reference conditions is calculated as


Suggested change

The dimensionless diode ideality factor :math:`n` is supplied by the user. The

modified ideality factor at reference conditions is calculated as

The dimensionless diode ideality factor :math:`n` is supplied by the user.

The modified ideality factor at reference conditions is calculated as

RDaxini · 2026-10-07T16:15:05Z

+    Villalva's basic parameter-extraction method increments the series
+    resistance from zero. For each candidate :math:`R_s`, the corresponding
+    :math:`R_{sh}`, :math:`I_L`, and :math:`I_0` are calculated and the
+    maximum power of the resulting single-diode model is evaluated. The
+    selected solution minimizes the absolute difference between modeled and
+    reference maximum power.


Suggested change

Villalva's basic parameter-extraction method increments the series

resistance from zero. For each candidate :math:`R_s`, the corresponding

:math:`R_{sh}`, :math:`I_L`, and :math:`I_0` are calculated and the

maximum power of the resulting single-diode model is evaluated. The

selected solution minimizes the absolute difference between modeled and

reference maximum power.

Villalva's parameter-extraction method is described in [1]_ and [2]. This

approach increments the series resistance from zero. For each candidate

:math:`R_s`, the corresponding :math:`R_{sh}`, :math:`I_L`, and :math:`I_0`

are calculated and the maximum power of the resulting single-diode

model is evaluated. The selected solution minimizes the absolute

difference between modeled and reference maximum power.

RDaxini · 2026-10-07T16:16:01Z

+    cells_in_series : int
+        Effective number of cells or junctions connected in series.
+    diode_factor : float
+        Dimensionless diode ideality factor used by the Villalva model.


Suggested change

Dimensionless diode ideality factor used by the Villalva model.

Dimensionless diode ideality factor. [unitless]

RDaxini · 2026-10-07T16:16:59Z

+    temp_ref : float, default 25
+        Reference cell temperature. [°C]
+    irrad_ref : float, default 1000
+        Reference irradiance. [W/m²]


Suggested change

Reference irradiance. [W/m²]

Reference irradiance. [Wm⁻²]

RDaxini · 2026-10-07T16:22:55Z

+    References
+    ----------
+    .. [1] M. G. Villalva, "Three-phase electronic power converter for a grid-connected photovoltaic system," 
+       PhD Thesis, Unicamp, 2010. DOI: 10.47749/T/UNICAMP.2010.781324
+    .. [2] M. G. Villalva, J. R. Gazoli, and E. Ruppert Filho, 
+       "Comprehensive Approach to Modeling and Simulation of Photovoltaic Arrays," 
+       IEEE Transactions on Power Electronics, 2009. DOI: 10.1109/TPEL.2009.2013862
+    """


@echedey-ls's suggestion to use the :doi sphinx role is correct but these lines are also >79 characters so will fail the flake8 checks. I am unsure why the failure isn't already marked in the diff. The references are also missing some bibliographic information (eg pages/volume), which need to be included in the IEEE format. I recommend the following:

Suggested change

References

----------

.. [1] M. G. Villalva, "Three-phase electronic power converter for a grid-connected photovoltaic system,"

PhD Thesis, Unicamp, 2010. DOI: 10.47749/T/UNICAMP.2010.781324

.. [2] M. G. Villalva, J. R. Gazoli, and E. Ruppert Filho,

"Comprehensive Approach to Modeling and Simulation of Photovoltaic Arrays,"

IEEE Transactions on Power Electronics, 2009. DOI: 10.1109/TPEL.2009.2013862

"""

References

----------

.. [1] M. G. Villalva, "Conversor eletrônico de potência trifásico para

sistema fotovoltaico conectado à rede elétrica," Ph.D. dissertation,

Faculdade de Engenharia Elétrica e de Computação, Universidade Estadual

de Campinas (UNICAMP), Campinas, Brazil, 2010.

:doi:`10.47749/T/UNICAMP.2010.781324`

.. [2] M. G. Villalva, J. R. Gazoli, and E. Ruppert Filho, "Comprehensive

approach to modeling and simulation of photovoltaic arrays," IEEE Trans.

Power Electron., vol. 24, no. 5, pp. 1198-1208, May 2009.

:doi:`10.1109/TPEL.2009.2013862`

"""

RDaxini · 2026-10-07T16:24:56Z

        return tracking_data

+def calcparams_villalva(
+    effective_irradiance,


Two blank lines needed for flake8

Suggested change

return tracking_data

def calcparams_villalva(

effective_irradiance,

return tracking_data

def calcparams_villalva(

effective_irradiance,

RDaxini · 2026-10-07T16:25:31Z

+    Parameters
+    ----------
+    effective_irradiance : numeric
+        Effective irradiance converted to photocurrent. [W/m²]


You can format like this throughout the docs

Suggested change

Effective irradiance converted to photocurrent. [W/m²]

Effective irradiance converted to photocurrent. [Wm⁻²]

RDaxini · 2026-10-07T16:26:29Z

+best_idx = history["abs_power_error"].idxmin()
+best = history.loc[best_idx]
+
+print(f"Best R_s = {best['R_s']:.6f} ohm")


false positive flake8 failure, I think. Don't add a space here (or on any of the other instances)

RDaxini · 2026-10-07T16:49:47Z

+
+from pvlib.ivtools.sdm.villalva import ( # noqa: F401
+    _villalva_params_at_rs,
+    fit_villalva,
+)


Fix the flake8 error by adding a space. I don't think we need to list the private helper here either

Suggested change

from pvlib.ivtools.sdm.villalva import ( # noqa: F401

_villalva_params_at_rs,

fit_villalva,

)

from pvlib.ivtools.sdm.villalva import ( # noqa: F401

_villalva_params_at_rs,

)

Add files via upload

8698c7a

JFrederico2022 added 6 commits October 6, 2026 14:51

Merge branch 'pvlib:main' into main

f468215

Delete pvlib/ivtools/sdm/Villalva.ipynb

16beb52

Add files via upload

07654d1

Update __init__.py

547f679

Update pvsystem.py

5f29b13

Add files via upload

51fdd23

RDaxini added enhancement api labels Oct 6, 2026

cwhanse reviewed Oct 6, 2026

View reviewed changes

JFrederico2022 and others added 3 commits October 6, 2026 21:09

Update pvlib/ivtools/sdm/villalva.py

eb878f6

Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

Update pvlib/ivtools/sdm/villalva.py

386c004

Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

Update villalva.py

308fe5f

echedey-ls reviewed Oct 7, 2026

View reviewed changes

cwhanse added this to the v0.16.2 milestone Oct 7, 2026

RDaxini reviewed Oct 7, 2026

View reviewed changes

	PhD Thesis, Unicamp, 2010. DOI: 10.47749/T/UNICAMP.2010.781324
	PhD Thesis, Unicamp, 2010. :doi:`10.47749/T/UNICAMP.2010.781324`

	IEEE Transactions on Power Electronics, 2009. DOI: 10.1109/TPEL.2009.2013862
	IEEE Transactions on Power Electronics, 2009. :doi:`10.1109/TPEL.2009.2013862`

		The dimensionless diode ideality factor :math:`n` is supplied by the user. The
		modified ideality factor at reference conditions is calculated as

	Dimensionless diode ideality factor used by the Villalva model.
	Dimensionless diode ideality factor. [unitless]

	Reference irradiance. [W/m²]
	Reference irradiance. [Wm⁻²]

-    References
-    ----------
-    .. [1] M. G. Villalva, "Three-phase electronic power converter for a grid-connected photovoltaic system,"
-       PhD Thesis, Unicamp, 2010. DOI: 10.47749/T/UNICAMP.2010.781324
-    .. [2] M. G. Villalva, J. R. Gazoli, and E. Ruppert Filho,
-       "Comprehensive Approach to Modeling and Simulation of Photovoltaic Arrays,"
-       IEEE Transactions on Power Electronics, 2009. DOI: 10.1109/TPEL.2009.2013862
-    """
+    References
+    ----------
+    .. [1] M. G. Villalva, "Conversor eletrônico de potência trifásico para
+       sistema fotovoltaico conectado à rede elétrica," Ph.D. dissertation,
+       Faculdade de Engenharia Elétrica e de Computação, Universidade Estadual
+       de Campinas (UNICAMP), Campinas, Brazil, 2010.
+       :doi:`10.47749/T/UNICAMP.2010.781324`
+    .. [2] M. G. Villalva, J. R. Gazoli, and E. Ruppert Filho, "Comprehensive
+       approach to modeling and simulation of photovoltaic arrays," IEEE Trans.
+       Power Electron., vol. 24, no. 5, pp. 1198-1208, May 2009.
+       :doi:`10.1109/TPEL.2009.2013862`
+    """

	Effective irradiance converted to photocurrent. [W/m²]
	Effective irradiance converted to photocurrent. [Wm⁻²]

Conversation

JFrederico2022 commented Oct 3, 2026 • edited by cwhanse Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 3, 2026

Hey @JFrederico2022! 🎉

Uh oh!

cwhanse commented Oct 4, 2026

Uh oh!

JFrederico2022 commented Oct 6, 2026

Uh oh!

Uh oh!

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!

ramaroesilva commented Oct 7, 2026

Uh oh!

RDaxini commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

echedey-ls commented Oct 7, 2026

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

JFrederico2022 commented Oct 3, 2026 •

edited by cwhanse

Loading

RDaxini commented Oct 7, 2026 •

edited

Loading

RDaxini left a comment •

edited

Loading