[JFrederico2022]

• 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]

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]

@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]

Hello, @cwhanse

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

Best regards,
João Frederico

[ramaroesilva]

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]

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]

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

[cwhanse]

@JFrederico2022 sorry for the delay here. Tests look OK to me. There's some formatting cleanup (mostly extra whitespace) in the Flake8 report.

[JFrederico2022]

@JFrederico2022 sorry for the delay here. Tests look OK to me. There's some formatting cleanup (mostly extra whitespace) in the Flake8 report.

Hi @cwhanse,

No worries, and thank you for reviewing the PR!

I've addressed the formatting issues reported by Flake8 and pushed the changes.

Thanks again for your feedback!

[RDaxini]

Thanks for keeping this moving forward @JFrederico2022
It's a big one, so this might still take some time. I have added a few more thoughts as I slowly digest this PR...
Reconciling input/output types (#2878 (comment)) and providing more useful error messages (#2878 (comment)) might be the highest priority, although the latter may require some discussion first.

[RDaxini]

I am unsure whether this is particularly helpful. The users never enters r_sh_min so do we not want to frame this in terms of one of the other user inputs? This value error would occur if, for example, v_mp=0, which is likely a typo from the user. Not saying we override the user making a mistake (garbage in garbage out, as usual) but I think the error message could be improved / framed in terms of user inputs rather than the internally calculated r_sh_min.

[JFrederico2022]

It is a valid point to consider, @RDaxini. I concur with your observation. In practical scenarios, this error may not occur frequently. I will review this message to enhance its quality. Thank you for bringing this to my attention.

[JFrederico2022]

Hi @RDaxini,

I've updated the error message as follows:

if r_sh_min <= 0:
raise ValueError(
"Invalid module specifications: the calculated minimum "
"shunt resistance is non-positive. Check the consistency "
"of v_mp, i_mp, v_oc, and i_sc."
)

I think this makes the error more informative by referring directly to the user inputs.

[RDaxini]

I think we need to do some work to reconcile input/output types. R_s and R_sh are returned as plain floats, and I_0/nNsVth only follow temp_cell's type, so the outputs don't match the input type.

You could probably recycle the block at the end of calcparams_desoto that converts all outputs to the input type, and then add calcparams_villalva to the parametrized test_calcparams_*_returns_correct_Python_type tests in tests/test_pvsystem.py.

[JFrederico2022]

Nice! I agree with you, @RDaxini.

[JFrederico2022]

Hi @RDaxini,

I've updated calcparams_villalva() to follow the same output-type handling approach used in calcparams_desoto(), ensuring consistent output types for scalar, NumPy array, and pandas Series inputs.

I've also added the parametrized test test_calcparams_villalva_returns_correct_Python_type() in tests/test_pvsystem.py.

Thanks for the suggestion!

[JFrederico2022]

@JFrederico2022 For the validation plot below, my understanding is that the Villalva model was fit to each temperature and irradiance condition separately. However, as I understand it, the original SDM paper describes using the Isc and Voc temperature coefficients to compute I0 away from STC (in particular, avoiding the need for a band gap parameter value). I am curious what the validation looks like using that extrapolation of the fit at STC, rather than separate "local" fits at different operating conditions. For PVfit, I have used IEC 61853-1 matrix measurements to assess how well a fit using STC conditions extrapolates to a wider set of conditions, and I have attached an example of that. (IIRC, this was a rather good fit, but other fits do not extrapolate so well away from STC.)

More pertinent to this PR, is the SDM using the Isc and Voc temperature coefficients implemented demonstrated here?

Hi @markcampanelli,

First, apologies for the delayed response, and thank you for your comments and for sharing the PVfit example!

The Villalva parameter extraction method can be applied independently at different operating conditions, provided that the corresponding I-V characteristic points are available. Alternatively, the parameters can be fitted once using the datasheet specifications at STC and then extrapolated to different irradiance and temperature conditions.

In the current example, I followed the second approach. The reference parameters are extracted only once using fit_villalva(), and calcparams_villalva() is then used to calculate the five SDM parameters at different operating conditions, without performing additional fits.

As you mentioned, the implementation uses the short-circuit current (alpha_sc) and open-circuit voltage (beta_voc) temperature coefficients to calculate the temperature-dependent diode saturation current (I0), without requiring an explicit bandgap parameter.

I agree that comparing these extrapolated curves against IEC 61853-1 measurements would provide a more comprehensive validation of the model's predictive performance. The current example demonstrates the extrapolation procedure rather than an independent experimental validation.

It might be helpful to clarify this distinction in the example documentation.

Beyond this PR, I think this could also be an interesting direction for future research. One possibility would be to investigate an optimization strategy for the Villalva model in which the reference parameters are selected to minimize the overall I-V curve prediction errors across the IEC 61853-1 irradiance-temperature matrix, rather than focusing only on reproducing the maximum power point at STC. Since the Villalva extraction procedure explores different candidate series resistances and their corresponding parameters, it could provide a useful starting point for investigating solutions that improve model accuracy across a wider range of operating conditions.

This could potentially lead to a more comprehensive parameter-fitting approach, with improved extrapolation performance compared with conventional STC-based fitting strategies.

Thanks again for your valuable feedback!

[cwhanse]

Needs an entry in the v0.16.2 whatsnew file.

[cwhanse]

Coverage is fine, I think. The uncovered lines are in the fitting code in villalva.py, raising errors when the fitting algorithm fails. I don't think it's worth creating tests that provoke those messages.