More common terms for solar zenith and solar azimuth

In pvlib, two solar zenith quantities are of interest: true (geometric) zenith angle, and apparent (refraction corrected) zenith angle. Currently, zenith, solar_zenith and apparent_zenith all appear in different places, and the meaning of each isn’t consistent throughout. For example, solarposition/spa_c uses zenith (true) and apparent_zenith (refraction-corrected), and Location methods expect these terms. But both apparent_zenith and solar_zenith are used in SingleAxisTracker methods (the latter without being specific in the docstring), and in places where I think refraction-corrected zenith should be expected, e.g., PVSystem.get_aoi.

For solar azimuth, there is not counterpart to true vs. refraction-corrected. But for the solar azimuth, both azimuth and solar_azimuth are being used.

Describe the solution you’d like

1. Agreement on the pvlib meaning of zenith and solar_zenith. apparent_zenith’s meaning is clear. The other two terms leave room for uncertainty.

2. Agreement on one term to use for solar azimuth: azimuth or solar_azimuth.

Describe alternatives you’ve considered It makes sense to have a term that is not specific to true or apparent zenith. Perhaps zenith for this use, and solar_zenith specifically for true zenith?

[cwhanse]

I am willing to draft a PR. If we are changing parameter names, what’s the machinery for deprecation? Add the new name and retain the old name, raising a warning if the old name is used?

[wholmgren]

So are we in agreement with https://github.com/pvlib/pvlib-python/issues/1403#issuecomment-1043363825 except for the geom/analytical name?

I generally agree with @mikofski on the descriptor order but we already have the solar_zenith_analytical function and I think consistency with that is a plus. If we are still looking for a more descriptive name, the function doc string mentions “spherical trigonometry” so maybe solar_zenith_spherical (or spherical_solar_zenith).

Thinking we should finalize this soon so that we can make a 0.9.1 release.