Skip to content

Fix iam.schlick_diffuse returning inf and nan at surface_tilt=180 - #2942

Open
G26karthik wants to merge 4 commits into
pvlib:mainfrom
G26karthik:fix-schlick-diffuse-tilt-180
Open

G26karthik wants to merge 4 commits into
pvlib:mainfrom
G26karthik:fix-schlick-diffuse-tilt-180

Conversation

@G26karthik

@G26karthik G26karthik commented Nov 10, 2026 •

Copy link
Copy Markdown
  • Closes iam.schlick_diffuse returns inf and nan at surface_tilt=180 #2939
  • 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.

Eq 4 divides by 1 + cos(surface_tilt), which is 0/0 when the surface faces straight down, so surface_tilt=180 gave sky=inf, ground=nan. The sky term is now 0 within 1e-6 degrees of 180, the same clamp the ground term already gets near 0, and ground comes out as 20/21 (the sky value at tilt 0).

Everywhere else the values are unchanged; I checked over 100,000 tilts from -90 to 360. One side effect: for a named Series input, sky no longer inherits the input's name, which matches ground.

Added test_schlick_diffuse_upside_down. tests/test_iam.py passes (60 tests) and flake8 is clean.

Eq 4 for the sky term divides by (1 + cos(tilt)), which is 0/0 for a
surface facing straight down. Return 0 (no visible sky) there, as is
already done for the ground term at tilt 0. The ground term then follows
from Eq 6 and equals 20/21, the sky value at tilt 0.
@github-actions

Copy link
Copy Markdown

Hey @G26karthik! 🎉

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.

@adriesse adriesse left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My all-time favourite model gets even better!

Comment thread pvlib/iam.py Resolved
Comment thread pvlib/iam.py Resolved
Comment thread pvlib/iam.py Resolved
@G26karthik

Copy link
Copy Markdown
Author

Thanks @adriesse, applied all three in 078467b. You're right about the wobble: Eq 4 is already off at 179.9999 (about 7e-5 where it should be near 5e-6) and gives 13.5 at 179.999999, so the 1e-6 cutoff was too tight. Same story for the ground term near 0.

@G26karthik

Copy link
Copy Markdown
Author

@adriesse whenever you have time, could you check whether 078467b settles your three points? GitHub doesn't let me re-request your review from my side.

@adriesse

adriesse commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Actually it's a bit surprising that this is occurring with a model that is analytically correct. I wonder if we can find an explanation before applying the band-aid?

@G26karthik

Copy link
Copy Markdown
Author

@adriesse It's floating-point cancellation rather than the model. At 180° the terms in the bracket of Eq 4 (up to about 24 in size) cancel exactly, and near 180° the bracket shrinks like (π − β)³ while 1 + cos β shrinks like (π − β)²/2, so the true value goes to 0 linearly. In float64 the bracket keeps a rounding error around 1e-15 that the small denominator magnifies: at 179.9999° Eq 4 should give 4.94e-6 (checked with 60-digit arithmetic), float64 gives 7.1e-5, and at 179.999999° it gives 13.5. Eq 6 has the same problem near 0°, and it equals the sky term at 180° − β exactly. So instead of the cutoffs I could use the limit 80/(9π)·(π − β) near 180° and compute the ground term from the sky term at 180° − β. Would that be better?

@adriesse

Copy link
Copy Markdown
Member

Looks promising, but could you elaborate a bit more in your explanation?

Also, did you check the influence of the fact that sind(180) is not exactly zero?

Near 180 degrees the bracket of Eq 4 cancels to about h**3 (h = 180 -
tilt in radians) while 1 + cos(tilt) is about h**2 / 2, so float64
rounding in the bracket dominates: the result was off by 2% at 0.001
degrees from 180 and by a factor of 13 at 0.0001 degrees.

Replace the cutoffs: within 0.3 degrees of 180 the sky term uses the
first three terms of the series of Eq 4 in h, and the ground term
(Eq 6) is computed as the sky term at 180 - tilt, which it equals
exactly; this also avoids the cancellation in Eq 6 near 0. Against Eq 4
in 60-digit arithmetic the largest relative error of both terms is now
below 1e-8.
@G26karthik

Copy link
Copy Markdown
Author

Sure. Write β = π − h. Of the eight terms in the bracket of Eq 4, only the first three are nonzero at h = 0, and they cancel exactly: 30π/7 − 160π/21 + 10π/3 = 0 (13.46 − 23.94 + 10.47). The other five carry a factor sin β. Expanded in h, the h⁰, h¹ and h² parts all cancel:

  • bracket = h³ (1600 − 675π h + 1216 h²) / 720 + O(h⁶)
  • 1 + cos β = h²/2 − h⁴/24 + …
  • cuk = h (4800 − 2025π h + 4048 h²) / (540π) + O(h⁴) ≈ 2.83 h

In float64 the three large terms are each rounded, so the computed bracket keeps an absolute error of 2e-16 to 2e-15 (measured), and dividing by about h²/2 magnifies it while cuk itself shrinks like 2.83 h. Against Eq 4 in 60-digit arithmetic, the float64 result is off by 1e-7 at 0.1° from 180°, 3e-5 at 0.01°, 2% at 0.001° and a factor of 13 at 0.0001°.

On sind(180): it returns 1.2246e-16, which is exactly π − fl(π), so it is the correct sine of the rounded angle radians(180) rather than an extra error. At 180° cosd is exactly −1.0, so the denominator is exactly 0, and the numerator is 8.4e-16: 1.8e-15 from rounding the three large terms and −0.9e-15 from the terms with sin β. So even with sin β set to exactly 0 the result would still be inf. Near 180° it isn't the cause either: feeding the formula β, sin β and cos β correctly rounded from 60-digit values gives results that are just as far off.

Eq 6 has the same problem near 0°, and it is exactly the sky term at 180° − β: sympy reduces the difference to 0, because (1 + cos β)·cuk(β) + (1 − cos β)·cuk(180° − β) = 40/21.

So in 264c895 I replaced the cutoffs: within 0.3° of 180° the sky term uses the series above, with h = radians(180 − tilt), which is exact in float64 there, so sind and cosd don't enter; and the ground term is computed as the sky term at 180° − β. Over about 10,000 tilts in [0, 180], down to 1e-14° from either end, the largest relative error against 60-digit Eq 4 is now 9.2e-9 for both terms. The updated test checks values near 180° against 60-digit Eq 4 and fails with the cutoff version.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

iam.schlick_diffuse returns inf and nan at surface_tilt=180

3 participants