Implement iam.schlick, iam.schlick_diffuse

[kandersolar]

• Closes Add iam function based on Schlick 1994 #1564
• 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.

Yu Xie from NREL presented a new IAM model at the recent PVPMC meeting (slides) and wanted to contribute it to pvlib. This one is a little unusual in that it calculates the IAM factor as a relative quantity, taking the indices of refraction of both the PV surface and the accompanying pyranometer into account.

[kandersolar]

I suppose we could move the diffuse calculations to a separate function like was done with martin_ruiz. It's a little strange to return scalar sky & ground IAM but time series direct IAM as the current code does for a fixed tilt simulation.

[kandersolar]

Offline discussion with @cwhanse and the model's author determined that the parameter this PR calls n_ref may have some niche uses but should be set to the same value as n for standard PV modeling workflows (unlike as assumed in the reference). That is now the default behavior.

I also added pvlib.iam.schlick in this PR as suggested in #1564.

[cwhanse]

I think there are some minor efficiency improvements that could be done in iam.fedis at the cost of less transparency when comparing to the reference. E.g., the default case n_ref=n means that term1 is identically 1. On the whole I am preferring transparency.

[adriesse]

Should/does fedis direct be equal to schlick? If not, why not?

[kandersolar]

Should/does fedis direct be equal to schlick? If not, why not?

Close-ish but not identical. FEDIS is using the true Fresnel equations for the direct component so it cannot match exactly. The Schlick approximation only comes in for the diffuse components: in the absence of an analytical integration of the real Fresnel equations, FEDIS's diffuse components are instead an integration of the Shlick approximation. It's the alternative to Marion's integration method -- whereas Marion's is an approximate integration of an exact integrand, FEDIS is an exact integration of an approximate integrand.

[adriesse]

Close-ish but not identical. FEDIS is using the true Fresnel equations for the direct component

I see, but we already have that in iam.physical, right?

[kandersolar]

I see, but we already have that in iam.physical, right?

Yes, with two minor differences: FEDIS does not consider extinction (i.e. it assumes K=0 in iam.physical), and FEDIS has the option to normalize the IAM profile with respect to another device with a different index of refraction. The latter is what prevents iam.physical from being a superset of FEDIS's direct IAM calculation. A separate index of refraction for the normal incidence normalization coefficient is probably only useful in unusual modeling scenarios, but nevertheless it is part of the model so I include it here.

For context, I have the sense that the FEDIS paper to some extent views its diffuse IAM equations as the primary scientific contribution with the direct component being included for completeness.

[cwhanse]

A little docstring tidying. OK with me to merge as is.

[adriesse]

Perhaps we should invite a additional reviewer on this one?

[adriesse]

It turns out that term1 in fedis_diffuse() is exactly the same as the weighting function w in fedis(), just in simplified form. I suggest making the code the same in both functions and referring to this ratio/weight/multiplier as w0. (Or the calculation could even be put in a separate helper function.)

For clarity, I would suggest using the long version because it shows what's actually going on, and putting the short version in a comment with reference to the paper.

[kandersolar]

For clarity, I would suggest using the long version because it shows what's actually going on, and putting the short version in a comment with reference to the paper.

I have kept the equations as-is so they continue being directly tied to the reference, but the latest commit at least leaves a comment noting the equivalence for any interested readers. Hopefully that achieves the same goal?

Perhaps we should invite a additional reviewer on this one?

I wouldn't mind input from additional reviewers here, but the three of us (@adriesse, @cwhanse, myself) reaching consensus would be good enough for me.

[kandersolar]

Following offline discussion, we have decided to move forward here with only the two schlick functions. I'll wait a few days to merge this to leave opportunity to review for anyone who wants to.

[kandersolar]

Thanks again for the thoughtful and productive discussion @adriesse and @cwhanse

[adriesse]

No problem. I learned a few things in the process!