Update zenith and azimuth angle documentation (#2485)

* docs: update solar angle definitions in nomenclature

- Add detailed definitions for solar angles with range constraints
- Clarify pvlib's east-of-north convention for azimuth angles
- Add cross-references between related terms using :term: directive
- Add coordinate system conventions for latitude/longitude
- Enhance existing angle definitions with usage notes and examples

This commit addresses issue #2448 by migrating angle definitions and
conventions from parameter descriptions to the nomenclature page.

(cherry picked from commit 16435c7)

* Add test script for solar angle calculations (Issue #2448)

- Created test_solar_angles.py to verify solar angle calculations
- Tests zenith, azimuth, and elevation angles for different times of day
- Uses New York City as example location on spring equinox
- Verifies angles are within expected ranges and follow correct patterns

(cherry picked from commit f202c5d)

* Remove test_solar_angles.py and integrate its functionality into tests/test_solarposition.py

- Deleted the standalone test_solar_angles.py file.
- Added a new test function, test_solar_angles_spring_equinox, to tests/test_solarposition.py.
- The new test verifies solar angles for New York City on the spring equinox, ensuring angles are within expected ranges and follow correct patterns.

(cherry picked from commit 9963629)

* remove aoi range statement

* add units

* rephrase pvlib azimuth angle convention

* remove "for example" from azimuth defintion

See #2448 (comment)

* remove zenith/azimuth range constraints

* remove "for example" again

* remove tests for angle range

* delete example.py

* remove blank line

* nomenclature revision

* so that -> so

* Update v0.13.1.rst

* add general technical descriptions/definitions

* Apply suggestions from code review

Co-authored-by: Cliff Hansen <[email protected]>

* vector pointed up and a vector...

Co-Authored-By: Cliff Hansen <[email protected]>

* surface_azimuth definition

* remove solar_elevation link

---------

Co-authored-by: RDaxini <[email protected]>
Co-authored-by: RDaxini <[email protected]>
Co-authored-by: Cliff Hansen <[email protected]>
Co-authored-by: Cliff Hansen <[email protected]>

Author: 3 people

docs/sphinx/source/user_guide/extras/nomenclature.rst

@@ -22,16 +22,24 @@ There is a convention on consistent variable names throughout the library:
 
     aoi
         Angle of incidence. Angle between the surface normal vector and the
-        vector pointing towards the sun’s center
+        vector pointing towards the sun's center. [°]
 
     aoi_projection
-        cos(aoi)
+        cos(aoi). When the sun is behind the surface, the value is negative.
+        For many uses, negative values must be set to zero.
 
     ape
         Average photon energy
 
     apparent_zenith
-        Refraction-corrected solar zenith angle in degrees
+        Refraction-corrected solar zenith angle. The solar
+        zenith angle describes the position of the sun relative to the vertical and is
+        defined as the angle between a vector pointed straight up and a vector pointed
+        at the sun, from the observer. [°]
+
+    apparent_elevation
+        Refraction-corrected solar elevation angle. This is the complement of
+        :term:`apparent_zenith` (90 - apparent_zenith). [°]
 
     bhi
         Beam/direct horizontal irradiance
@@ -87,10 +95,10 @@ There is a convention on consistent variable names throughout the library:
         Sandia Array Performance Model IV curve parameters
 
     latitude
-        Latitude
+        Latitude in decimal degrees. Positive north of equator, negative to south.
 
     longitude
-        Longitude
+        Longitude in decimal degrees. Positive east of prime meridian, negative to west.
 
     pac, ac
         AC power
@@ -141,10 +149,15 @@ There is a convention on consistent variable names throughout the library:
         Diode saturation current
 
     solar_azimuth
-        Azimuth angle of the sun in degrees East of North
+        Azimuth angle of the sun in degrees East of North. The solar azimuth angle
+        describes the sun’s position along the horizon relative to the observer.
+        The pvlib-python convention is defined as degrees East of North, so
+        North = 0°, East = 90°, South = 180°, West = 270°.
 
     solar_zenith
-        Zenith angle of the sun in degrees
+        Zenith angle of the sun in degrees. This is the angle between is between a
+        vector pointed straight up and a vector pointed at the sun, from the observer.
+        This is the complement of solar elevation (90 - elevation). [°]
 
     spectra
     spectra_components
@@ -154,11 +167,16 @@ There is a convention on consistent variable names throughout the library:
         is composed of direct and diffuse components.
 
     surface_azimuth
-        Azimuth angle of the surface
+        Azimuth angle of the surface in degrees East of North. This angle describes the
+        horizontal projection of the normal vector from the surface. The pvlib-python
+        convention is defined as degrees East (clockwise) of North, so North = 0°,
+        East = 90°, South = 180°, West = 270°.
 
     surface_tilt
-        Panel tilt from horizontal [°]. For example, a surface facing up = 0°,
-        surface facing horizon = 90°.
+        Tilt from horizontal [°]. The surface tilt angle 
+        is defined as degrees from the horizontal
+        such that a surface facing up would have a surface tilt of 0°, and one facing
+        the horizon would be 90°.  [°]
 
     temp_air
         Temperature of the air

docs/sphinx/source/whatsnew/v0.13.1.rst

@@ -23,6 +23,8 @@ Enhancements
 
 Documentation
 ~~~~~~~~~~~~~
+* Substantiate definitions of solar/surface azimuth/zenith and aoi on the
+  :ref:`nomenclature` page. (:issue:`2448`, :pull:`2503`)
 
 
 Testing
@@ -45,3 +47,5 @@ Maintenance
 Contributors
 ~~~~~~~~~~~~
 * Elijah Passmore (:ghuser:`eljpsm`)
+* Rajiv Daxini (:ghuser:`RDaxini`)
+* Omar Bahamida (:ghuser:`OmarBahamida`)