Shaded Fraction on Sloped Terrains - PR1725 partial continuation

[echedey-ls]

• Closes Add shaded fraction (FS) calculation for true-tracking on flat terrain #1689
• Add linear shade loss model for thin film #1690
• Partially substitutes Linear shade gh1690 #1725
• 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.

See #1725 for context.

Link to docs

• pvlib.shading.shaded_fraction1d
  • gallery example
• pvlib.shading.linear_shade_loss

I moved the linear loss model to #2004

Feel free to suggest anything and ask about the adopted solutions.

[kandersolar]

Does, for example, a N-S SAT tracker azimuth follow the East - West direction or the torque tube? I would say the azimuth and elevation define the normal vector of any PV panel on it, but I'm not at all sure.

A distinction needs to be drawn between the angles that define the orientation of tracker and the angles that define the orientation of the modules on the tracker. A single-axis tracker with N-S axis has constant axis_azimuth=180 (or zero, but 180 is better). The modules on the tracker will have surface_azimuth=90 in the morning and surface_azimuth=270.

I will take a closer look at this PR in the coming days. Thanks for your patience @echedey-ls!

[echedey-ls]

Lot of thanks for clearing this up. Now I feel like it's obvious.

Don't worry about the review. I know it's premature to open a PR based on another one (I've got yet another one in the drawer that needs this implementation to work, sorry 😬 )

[williamhobbs]

I'm late jumping in here, but one thought I have: does this need to be limited to trackers? Or can the function name and variable names be updated to more generally cover fixed or tracking rows?

[mikofski]

It should work for fixed tilt just fine, so not limited to trackers

[williamhobbs]

Thanks, @mikofski. It seems like it would be helpful to change:

• the function name from tracker_shaded_fraction to shaded_fraction,
• the variables tracker_tilt and tracker_azimuth to surface_tilt and surface_azimuth, and
• references in the docs to “trackers” to “rows”

or something like that.

[mikofski]

Maybe I misspoke. Sorry, I meant to say that it could be repurposed for fixed tilt with some care, but, I’m not sure if we should make it all purpose for both fixed tilt & SAT. For one, tracker azimuth and surface azimuth mean different things, so we can’t just swap them.

I think it would work if we treat fixed tilt as a tracker aligned east to west and set the tracker azimuth to either 90° or 270° measured clockwise from north, or 90° from the surface azimuth. Like a similar issue you raised recently, if azimuth were 90° then tilts would be negative if north and positive if south.

Currently this algorithm doesn’t seem to account for tracker axis tilt, but as I mentioned in the original PR #1725 I think it could be managed when calculating projected solar zenith? A tracker axis tilt would correspond to an east-west slope for a fixed tilt.

Anyway I apologize for being too glib, I should have been more careful in my replies, again sorry.

[echedey-ls]

I agree with @williamhobbs. surface_tilt and surface_azimuth terms seem to apply to all contexts independently of the used tracker, so they are less prone to be misunderstood by a user.

[kandersolar]

The docs build is failing because the example gallery is still using the old parameter names. Other than that, LGTM!

FYI I believe @AdamRJensen plans to review as well.

[echedey-ls]

Well spotted, I always miss something...

FYI I believe @AdamRJensen plans to review as well.

All feedback is welcome, even better if it comes from one of the authors 😉

[AdamRJensen]

An initial review of the gallery example

[AdamRJensen]

Could you add a comment about what this represents?

[echedey-ls]

Let me know your opinion on axis_tilt = 3 # degrees, positive is upwards in the axis_azimuth direction (edit: already commited)

[AdamRJensen]

Awesome stuff @echedey-ls !

I'm really looking forward to using this.

[echedey-ls]

Everything's ready IMO 😄 . Feel free to review and propose changes 📝

[kandersolar]

I just fixed a syntax issue and linter issue, and then fixed a new syntax issue I introduced...

Thanks for this great contribution @echedey-ls!

[echedey-ls]

Excited to see this merged! Thanks to everyone that helped move this forward!!