[BUGFIX] Inconsistent naming of cross_axis_tilt / cross_axis_slope

[echedey-ls]

• Closes cross_axis_slope vs cross_axis_tilt #2334
• I am familiar with the contributing guidelines
• Tests added
• [NA] 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`).
• [NA] 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.

pvlib.shading.shaded_fraction1d uses 'cross_axis_slope' as an input, while pvlib.tracking.singleaxis uses 'cross_axis_tilt'. I think these are the same thing - is that correct? If so, would it make sense to update one of them to be consistent?

Extract from the body message, OP @williamhobbs, #2334 .

Also adds variable description to nomenclature page.

Relevant doc pages

• https://pvlib-python--2543.org.readthedocs.build/en/2543/user_guide/extras/nomenclature.html#term-cross_axis_tilt
• https://pvlib-python--2543.org.readthedocs.build/en/2543/reference/generated/pvlib.shading.shaded_fraction1d.html
• https://pvlib-python--2543.org.readthedocs.build/en/2543/reference/generated/pvlib.tracking.singleaxis.html

[echedey-ls]

Currently targets v0.13.1, but I leave this decision up to anybody else (please, assign milestone accordingly). I will update deprecations tracker when merged.

[AdamRJensen]

Suggested change

removal="0.15.0",

We usually don't specify a removal version as there's not standard timeline for when minor versions come out. If we really wanted to specify a removal, I think this should be in the form of a date, e.g., removal="Earliest September 2026".

[echedey-ls]

I never thought of that, but looks a promising idea

[AdamRJensen]

I'm interested in what @wholmgren thinks of this?

[wholmgren]

Sorry I missed this for a few weeks. I don't think timeline is particularly relevant so long as we are using SemVer (or something close to it). I personally think we should specify removal versions, they should default to the 0.(m+2).0 release, and we should use our existing test machinery to enforce that. If we had several minor releases in a very short period of time (a few weeks) then I'd be ok pushing out the removal to a future release.

[AdamRJensen]

The original thread #2334 contained multiple views in favor of cross_axis_slope over cross_axis_tilt. This PR currently implements the latter. Is there a reason for this?

[echedey-ls]

Thanks for the reviews.

@AdamRJensen , yeah, my fault. This is a stale branch I had locally - I guess I took that decision to conform with what already was the term prior to the newer feature and just skimmed through the discussion. I will change this whenever I can to reflect what was discussed.

[echedey-ls]

After a deeper review on the required changes to port cross_axis_tilt to cross_axis_slope, note that we don't only have what was discussed in #2334:

1. cross_axis_tilt as parameter in pvlib.tracking.singleaxis

But some other occurrences that could come along with the same renaming:

2. Function name/signature pvlib.tracking.calc_axis_tilt
3. Function name/signature pvlib.tracking.calc_cross_axis_tilt
4. Dataclass field cross_axis_tilt in pvlib.pvsystem.SingleAxisTrackerMount

The other way around is what is currently implemented in this PR, cross_axis_slope to cross_axis_tilt:

5. cross_axis_slope as parameter in pvlib.shading.shaded_fraction1d

I personally would prefer coherence among all of them. Either tilts or slopes. An example of what I mean, if I only address 1., singleaxis would take cross_axis_slope, that would be calculated with calc_cross_axis_tilt. Feels weird to me.

Note 1. and 5. are solvable with the renamed kwarg warning util; 2. and 3. by copying the new signature into an old reference variable, prior decoration with the deprecated util. À la:

# allow deprecated name from calc_cross_axis_slope
# (original name was calc_cross_axis_tilt)
calc_cross_axis_tilt = deprecated(
    since="0.13.1", alternative="pvlib.tracking.calc_cross_axis_slope"
)(calc_cross_axis_slope)

Regarding 4., I have my doubts. Thou probably populating and overriding its __init__, then decorating it with the renamed kwarg util would work.

To sum, my points:

a. To which extent do we want to rename *_axis_tilts into *_axis_slopes? Regarding tracker axes on the terrain.
b. Should we abide to the known precedent?
c. The number of deprecations, if we push towards all of them, that's 1 vs 4.

My two opinionated cents:
a. I lean towards consistency, i.e., renaming either all or none.
b. It's not like tilt is wrong, it's looks to me it's just a nuance between the options, and to distinguish it from surface tilt [0, 90]º.
c. As long as my opinionated b. is not flawed, I suggest prioritising user experience.

Nonetheless, a weak opinion. Please leave your opinion and suggestions. I will do as requested.

CC: @pvlib/pvlib-maintainer

[mikofski]

I believe we selected “tilt” versus slope because we wanted to distinguish between the “tilt” of the plane containing tracker axes versus the slope of the underlying terrain which might differ and is not relevant to the tracker rotation calculation. IMO slope has a connotation that implies terrain.

[williamhobbs]

I added a comment in the issue, #2334 (reply in thread), but I'll duplicate it here:

I'll caveat this with noting that I don't think it matters too much, but I still prefer "slope."

For example, I can mention "slope-aware backtracking," and it is relatively unambiguous what I am talking about. If I were instead to mention "tilt-aware backtracking," I think the meaning is lost.

And I informally asked a few non-solar folks in the office about the image below. Everyone said the angle of B should be "tilt" and C should be "slope" or "incline." When I said B has to be "tilt" and asked if A should be "tilt" or "slope", everyone liked "slope" more and said that "tilt" would be confusing. One person did mention that slope makes them think of "rise over run"...