Martinez shading factor

[echedey-ls]

• Closes Shading model that takes into account the bypass diodes and layout of modules #2063
• 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.

Addresses adding the shading model described in #2063, which divides the modules into blocks, i.e. groups of cells protected by bypass diodes. It is applied to the unshaded output power.

Tests have been made with the original paper data, that is not explicitly in the paper.

The most difficult part of this model is documenting the blocks IMO. Please have a look at it.

• Docs links

  • https://pvlib-python--2070.org.readthedocs.build/en/2070/reference/generated/pvlib.shading.direct_martinez.html
  • https://pvlib-python--2070.org.readthedocs.build/en/2070/gallery/shading/plot_martinez_shade_loss.html

[echedey-ls]

Ready for another review guys!! @kandersolar @cwhanse and everyone else ^.^

[kandersolar]

I don't quite understand the need of three variables here

I wondered the same thing as I was typing it out :) I more intended to just list the variables in the equations. I'm not saying we should necessarily use that specific function signature (although I see my comment could easily be read that way).

I'm not familiar with pvlib widely using it.

Not widely used, but sometimes used. It is currently available from some transposition models (e.g. pvlib.irradiance.perez) and perhaps someday the rest as well (#1553).

Anyway yes I agree, dropping the poa_circumsolar probably makes sense. I suggest keeping poa_direct and mentioning in the docstring that it should be given the sum of direct+circumsolar.

[echedey-ls]

Thank you very much for your reviews @kandersolar & @cwhanse ❣️

From my side, I think all comments have been addressed.

[AdamRJensen]

Just minor details

[AdamRJensen]

I don't understand what "cancels" means in this context

[echedey-ls]

I've changed the verb to "zeroes":

This experimental model zeroes a fraction of the direct and circumsolar

I may have not translated that correctly. I've seen "to zero" as a verb. Should I reword it to something along This experimental model decreases a fraction of the direct and circumsolar with each shaded block

[AdamRJensen]

Let's use the word reduces

This experimental model reduces a fraction of the direct and circumsolar with each shaded block

[AdamRJensen]

If one of its cells is "partly" shaded or "completely" shaded?

[echedey-ls]

A block is shaded when at least one of its cells is shaded. A first possibility is to consider that the power of a block is fully cancelled when the block is shaded.

The paper does not specify it, but from the original tests spreadsheet I confirm they are considered shaded if a minimal amount of shade impacts on them.

[echedey-ls]

I've added partially to the docstring, thou maybe I shouldn't.

[AdamRJensen]

I like it! Especially if you've confirmed with the spreadsheet

[kandersolar]

Great contribution @echedey-ls!