make projected solar zenith a convenience function

[mikofski]

Is your feature request related to a problem? Please describe.

A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

As mentioned in #1725 (comment) the projected solar zenith (PSZ) is used more than once, and may benefit from having a standalone function for reuse to remove redundant code.

Describe the solution you'd like

A clear and concise description of what you want to happen.

a new function perhaps in tools or tracking like this:

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))))

Describe alternatives you've considered

A clear and concise description of any alternative solutions or features you've considered.

For linear shade calculation in #1725 the user is required to calculate PSZ externally.

Additional context

Add any other context or screenshots about the feature request here.

one version of the PSZ calculation is currently in tracking.py based on the solar vector as seen in the orientation of the tracker axes, that's why axis tilt appears in this "transformed" solar vector:

xp = x*cos_axis_azimuth - y*sin_axis_azimuth
zp = (x*sin_axis_tilt*sin_axis_azimuth
          + y*sin_axis_tilt*cos_axis_azimuth
          + z*cos_axis_tilt)

pvlib-python/pvlib/tracking.py

Line 432 in 275e671

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

[kandersolar]

I'm definitely in favor of having a function to calculate this quantity. It's a step towards #1581 (comment).

[adriesse]

This angle is also referred to as the profile angle sometimes, correct?

[echedey-ls]

This angle is also referred to as the profile angle sometimes, correct?

I'd like to know that too, in order to contribute to this issue and move forward #1725

[mikofski]

IDK the correct name for this. If anyone has a stronger opinion please weigh in, otherwise @echedey-ls just go with “profile angle” as @adriesse suggests. As long as it’s well defined, hopefully that should be enough. Do not let perfect be the enemy of good.

[kandersolar]

I've not heard "profile angle" before. I think I recall hearing a tracker manufacturer call it the "projected solar zenith angle", and that's what I call it too.

I think what we implement ought to account for axis_tilt and axis_azimuth. Where should it live? pvlib.tracking and pvlib.shading seem appropriate to me. If this function is intended to be user-facing (which I think it should be), I'd be -1 to putting it in pvlib.tools.

Options for references:

• Lorenzo et al 2011: https://doi.org/10.1002/pip.1085
• Marion & Dobos 2013: https://doi.org/10.2172/1089596
• Anderson & Mikofski 2020: https://doi.org/10.2172/1660126

Once the new function is created, I think pvlib.tracking.singleaxis should call it, and calls to pvlib.bifacial.utils._solar_projection_tangent should be replaced with calls to it.

[echedey-ls]

I don't get how axis_tilt and axis_azimuth should be implemented here. @kandersolar can you point me to any equation that takes that into account?

Edit: at least on the last two papers which have many more equations I don't know what would be implemented.

[kandersolar]

The relevant equations are Eq 1 with Eq 11 for $\omega_{ID}$ in Lorenzo, or Eq 7 for $R$ in Marion, or Eq 5 for $\theta_T$ in Slope-Aware Backtracking. They use different symbols, but I think the math is all equivalent. Section 7, step 3 in Slope-Aware Backtracking might be helpful.

[wholmgren]

Where should it live? pvlib.tracking and pvlib.shading seem appropriate to me. If this function is intended to be user-facing (which I think it should be), I'd be -1 to putting it in pvlib.tools.

I'm also -1 to a user facing function in pvlib.tools. pvlib.irradiance is a bit of a junk drawer, but is it more appropriate than the relatively specific pvlib.tracking and pvlib.shading? At the risk of scope creep and unwise API deprecations, geometry.py came to mind for this and the AOI functions in irradiance.

[echedey-ls]

I'm in favour of a geometry.py or something along angles.py or angular.py for this function, aoi and aoi_projection. I didn't expect the latter two to be in irradiance.py

[adriesse]

For the curious:

https://www.google.com/search?q=%22profile+angle%22+sun

[cwhanse]

For me, aoi.py > geometry.py. Into shading.py seems like a last resort. My thought is that a user might guess a function like this would be in aoi.py and wouldn't know what to expect of geometry.py.