Linear shade gh1690

[mikofski]

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

add functions to get shaded fraction and calculate linear shade loss
ICYMI: @williamhobbs

Example:

>>> from pvlib import shading
# trivial case with tracker and psz at 45-deg no cross-axis slope, and gcr=0.8
>>> fs = shading.tracker_shaded_fraction(45.0, 0.8, 45.0, 0)
>>> loss = shading.linear_shade_loss(fs, 0.2)
>>> P_no_shade = 100  # [kWdc]  DC output from modules
>>> P_linear_shade = P_no_shade * (1-loss)  # [kWdc] output after loss
# 90.71067811865476 [kWdc]

[mikofski]

@kandersolar & @williamhobbs thanks for the feedback! I've addressed it. Can you review again?

[mikofski]

👀 derivations and figures added to tracker_shaded_fraction() docstring

[AdamRJensen]

Doesn't this function do the same as this existing function:

pvlib-python/pvlib/bifacial/infinite_sheds.py

Line 346 in 275e671

def _shaded_fraction(solar_zenith, solar_azimuth, surface_tilt,

[AdamRJensen]

It seems like it would be a lot easier for the user if the parameter was simply solar_zenith and the calculation to the projected solar zenith could be done behind the scenes (there should be a function for that in pvlib somewhere).

[mikofski]

The calculation for psz requires at least one additional argument, the solar azimuth and is not a trivial calculation:

sp = pvl.solarposition.get_solarposition(times, latitude, longitude, ...)
proj_zenith = np.degrees(np.arctan2(
    np.sin(np.radians(sp.azimuth))*np.sin(np.radians(sp.apparent_zenith)),
    np.cos(np.radians(sp.apparent_zenith))))

It is already in pvlib here:

pvlib-python/pvlib/tracking.py

Line 432 in 275e671

wid = np.degrees(np.arctan2(xp, zp))

which made me discover a typo in the comments here:

pvlib-python/pvlib/tracking.py

Line 421 in 275e671

# vector (xp, yp, zp) in the (y, z) plane, which is normal to the panel and

should be the (x, z) plane, which is corrected lower down here:

pvlib-python/pvlib/tracking.py

Line 429 in 275e671

# Calculate angle from x-y plane to projection of sun vector onto x-z plane

Anyway, I agree, it would be helpful to have PSZ as it's own function. And if it already exists in addition to tracking.py:432 then we should consolidate. I think it's out of scope for this PR, though so I'll open another one for that.

[mikofski]

I've created #1734 to propose a stand alone PSZ function, but in the process, realized that the existing use in tracking.py actually calculates the solar vector as observed in the reference frame of the tracker axes, which may be tilted north or south. So this new function would need to be generalized to different reference frames.

I'm coming around to this idea. One instant advantage of this standalone function would be generalization of this linear shade loss function to arbitrary slopes that have both NS and EW tilt! Thanks! However, I still think it's best to address separately, then return to this function to enhance it with the axis tilt and the solar azimuth.

[AdamRJensen]

Suggested change

	Shade fraction (FS) for trackers with a common angle on an east-west slope.
	Shade fraction for trackers with a common angle on an east-west slope.

The acronym is never used anywhere

[mikofski]

Doesn't this function do the same as this existing function: pvlib.bifacial.infinite_sheds._shaded_fraction()

They differ in that the new function allows the array to be on a cross axis slope. If we adapt the infinite sheds model to allow arbitrary orientation, then we could reuse this function, but that work was delayed due to some questions about where the horizon should be and what the sky and ground view factors would include. Until those issues are resolve and that enhancement is implemented, this new shaded fraction function is more generalized.

[mikofski]

The acronym is never used anywhere

It was the acronym that @williamhobbs used in #1689 and it's used on L269 in the source and L301 in the docstring example. Anyway, I'm not attached to it.

[williamhobbs]

I used "FS" for shaded fraction because Lorenzo 2011 used it, but I think it is confusing - should it be F_s, it's easily confused with "First Solar" in this context, etc.

[kandersolar]

@mikofski can you comment on the relationship between this shaded fraction calculation and the one in section 6 of Slope-Aware Backtracking? They seem quite similar in spirit, to me at least.

One thing I notice is that the cross-axis slope currently seems to be a left-handed rotation (assuming it is defined on the same axis as the tracker and sun angles), see here:

In [9]: tracker_shaded_fraction(tracker_theta=80, gcr=0.5, projected_solar_zenith=80, cross_axis_slope=0)
Out[9]: array(0.65270364)

In [10]: tracker_shaded_fraction(tracker_theta=80, gcr=0.5, projected_solar_zenith=80, cross_axis_slope=10)
Out[10]: array(1.)

In [11]: tracker_shaded_fraction(tracker_theta=80, gcr=0.5, projected_solar_zenith=80, cross_axis_slope=-10)
Out[11]: array(0.30540729)

[williamhobbs]

@AdamRJensen Did you tell me this week that if this used surface_tilt instead of tracker_theta, that it would also work for fixed tilt systems? That would be nice, but maybe I misunderstood.

Semi-related, do we need an array azimuth input, or is this only suitable for trackers with 180 deg azimuth? My implementation only worked for that case, but it maybe isn't ideal. We do have some true-tracking projects with not-180 azimuths (e.g., 168 deg). This might be scope-creep...

[echedey-ls]

What is pending to do in this PR? It has become of interest to me because I'd like to contribute a losses model that benefits from this calculation. (Conversation at G Groups, from end of September & start of October)

[mikofski]

What is pending to do in this PR? It has become of interest to me because I'd like to contribute a losses model that benefits from this calculation. (Conversation at G Groups, from end of September & start of October)

We got stuck considering consolidation & reuse of some private or intermediate calculations elsewhere (tracking & infinite sheds) that would either require extra work or would generalize this function to more relaxed conditions. Currently this is only good for N-S tracker (or possibly E-W fixed tilt) systems with perpendicular cross axis slopes.

Another sticking point was whether user should have to calculate PSZ (projected solar zenith) or not. I opened a separate issue for that.

So I’m not sure where we go from here. I think @williamhobbs submitted some PR’s recently that may have helped move this one forward as well?

[williamhobbs]

I think @williamhobbs submitted some PR’s recently that may have helped move this one forward as well?

@echedey-ls, @mikofski is correct, this PR https://github.com.mcas.ms/pvlib/pvlib-python/pull/1871 will let users get shaded fraction from infinite_sheds.get_irradiance and .get_irradiance_poa. It can be used for bifacial and monofacial systems with any azimuth, but not on sloped terrain.

[mikofski]

@echedey-ls if you’re interested in helping resolve the blockers and pushing this across the finish line that would be great. This PR is still important to me specifically because it provides a r2r shading solution for sloping terrain.

[echedey-ls]

@mikofski I'm interested in it too for the linked conversation model, but I've got to have a deeper look at the discussion and the code.

[echedey-ls]

@mikofski I'd like to start working on this PR based on the work of #1904 if you don't mind. I'd open a new PR based on this branch, although I also want to keep the conversations. IDK if I can be given write permission just for a branch, I don't think so...

[mikofski]

Thanks! It’s okay to branch my branch, looking forward to seeing this closed finally!