Possible improvement to pvlib.soiling.hsu documentation

[ramaroesilva]

Describe the bug hsu model documentation mentions that the output

soiling_ratio (Series) – Values between 0 and 1. Equal to 1 - transmission loss.

While the soiling ratio ranges 0-1, broadly speaking, it is also true that this model internally caps its minimum value at 0.6563 (i.e., 1-0.3437). For example, in the kimber model this cap is a user-defined parameter.

To Reproduce Steps to reproduce the behavior:

1. Go to hsu model documentation
2. Check the description of the returned output

Expected behavior The documentation could mention that the model implicitly defines a minimum value for the soiling ratio of 0.6563.

Versions:

• pvlib.__version__: 0.13.0

[cwhanse]

+1 to adding the HSU equation and a note to the function docstring.

Keep in mind that hsu and kimber return different quantities. hsu returns the soiling ratio, a fraction of irradiance. kimber returns a daily electrical energy loss. So the cap max_soiling in kimber is different that the unnamed maximum in hsu.

[mikofski]

I agree with Cliff, this is about the max loss. The wording of this issue was confusing to me, because as Cliff points out, the HSU model yields the soiling ratio which is defined in the documentation as 1 - transmission loss. Therefore, a soiling ratio of 100% means there is 0% transmission loss. Those of us used to using the Kimber model are thinking more of the loss rather than the soiling ratio so the way min and max were used in the question was confusing. Therefore, I agree with @ramaroesilva that a note in the documentation that the max loss is limited to 65% would be valuable. And for comparison, as Cliff pointed out, the Kimber model allows user to directly set the max_soiling loss which defaults to 30%.