Merge branch 'main' into irradiance_updates

RDaxini · web-flow · commit 0a8a432d404e · 2025-07-29T17:54:58.000-06:00
diff --git a/README.md b/README.md
@@ -74,7 +74,7 @@ Installation
 ============
 
 pvlib-python releases may be installed using the ``pip`` and ``conda`` tools.
-Please see the [Installation page](https://pvlib-python.readthedocs.io/en/stable/user_guide/installation.html) of the documentation for complete instructions.
+Please see the [Installation page](https://pvlib-python.readthedocs.io/en/stable/user_guide/getting_started/installation.html) of the documentation for complete instructions.
 
 
 Contributing
diff --git a/docs/examples/agrivoltaics/plot_agrivoltaics_ground_irradiance.py b/docs/examples/agrivoltaics/plot_agrivoltaics_ground_irradiance.py
@@ -59,7 +59,7 @@
 
 tracking_orientations = pvlib.tracking.singleaxis(
     apparent_zenith=solpos['apparent_zenith'],
-    apparent_azimuth=solpos['azimuth'],
+    solar_azimuth=solpos['azimuth'],
     axis_azimuth=axis_azimuth,
     max_angle=max_angle,
     backtrack=True,
diff --git a/docs/examples/shading/plot_martinez_shade_loss.py b/docs/examples/shading/plot_martinez_shade_loss.py
@@ -90,7 +90,7 @@
 
 tracking_result = pvlib.tracking.singleaxis(
     apparent_zenith=solar_apparent_zenith,
-    apparent_azimuth=solar_azimuth,
+    solar_azimuth=solar_azimuth,
     axis_tilt=axis_tilt,
     axis_azimuth=axis_azimuth,
     max_angle=(-90 + cross_axis_tilt, 90 + cross_axis_tilt),  # (min, max)
diff --git a/docs/examples/solar-tracking/plot_single_axis_tracking.py b/docs/examples/solar-tracking/plot_single_axis_tracking.py
@@ -33,7 +33,7 @@
 
 truetracking_angles = tracking.singleaxis(
     apparent_zenith=solpos['apparent_zenith'],
-    apparent_azimuth=solpos['azimuth'],
+    solar_azimuth=solpos['azimuth'],
     axis_tilt=0,
     axis_azimuth=180,
     max_angle=90,
@@ -61,7 +61,7 @@
 for gcr in [0.2, 0.4, 0.6]:
     backtracking_angles = tracking.singleaxis(
         apparent_zenith=solpos['apparent_zenith'],
-        apparent_azimuth=solpos['azimuth'],
+        solar_azimuth=solpos['azimuth'],
         axis_tilt=0,
         axis_azimuth=180,
         max_angle=90,
diff --git a/docs/examples/solar-tracking/plot_single_axis_tracking_on_sloped_terrain.py b/docs/examples/solar-tracking/plot_single_axis_tracking_on_sloped_terrain.py
@@ -100,7 +100,7 @@
 for cross_axis_tilt in [0, 5, 10]:
     tracker_data = tracking.singleaxis(
         apparent_zenith=solpos['apparent_zenith'],
-        apparent_azimuth=solpos['azimuth'],
+        solar_azimuth=solpos['azimuth'],
         axis_tilt=0,  # flat because the axis is perpendicular to the slope
         axis_azimuth=180,  # N-S axis, azimuth facing south
         max_angle=90,
@@ -156,7 +156,7 @@
 
 tracker_data = tracking.singleaxis(
     apparent_zenith=solpos['apparent_zenith'],
-    apparent_azimuth=solpos['azimuth'],
+    solar_azimuth=solpos['azimuth'],
     axis_tilt=axis_tilt,  # no longer flat because the terrain imparts a tilt
     axis_azimuth=axis_azimuth,
     max_angle=90,
diff --git a/docs/sphinx/source/user_guide/extras/nomenclature.rst b/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
diff --git a/docs/sphinx/source/whatsnew/v0.13.1.rst b/docs/sphinx/source/whatsnew/v0.13.1.rst
@@ -10,7 +10,8 @@ Breaking Changes
 
 Deprecations
 ~~~~~~~~~~~~
-
+* Rename parameter name ``aparent_azimuth`` to ``solar_azimuth`` in :py:func:`~pvlib.tracking.singleaxis`.
+  (:issue:`2479`, :pull:`2480`)
 
 Bug fixes
 ~~~~~~~~~
@@ -26,6 +27,8 @@ Documentation
   parameter definitions from the nomenclature page, ensure consistent
   parameter description structure, add units to all parameters where required,
   and other miscellaneous edits. (:issue:`2205`, :issue:`2248`, :pull:`2311`)
+* Substantiate definitions of solar/surface azimuth/zenith and aoi on the
+  :ref:`nomenclature` page. (:issue:`2448`, :pull:`2503`)
 
 
 Testing
@@ -48,4 +51,5 @@ Maintenance
 Contributors
 ~~~~~~~~~~~~
 * Elijah Passmore (:ghuser:`eljpsm`)
-* Rajiv Daxini (:ghuser:`rdaxini`)
+* Rajiv Daxini (:ghuser:`RDaxini`)
+* Omar Bahamida (:ghuser:`OmarBahamida`)
diff --git a/pvlib/bifacial/pvfactors.py b/pvlib/bifacial/pvfactors.py
@@ -1,6 +1,6 @@
 """
 The ``bifacial.pvfactors`` module contains functions for modeling back surface
-plane-of-array irradiance using an external implementaton of the pvfactors
+plane-of-array irradiance using an external implementation of the pvfactors
 model (either ``solarfactors`` or the original ``pvfactors``).
 """
 
diff --git a/pvlib/ivtools/sdm/_fit_desoto_pvsyst_sandia.py b/pvlib/ivtools/sdm/_fit_desoto_pvsyst_sandia.py
@@ -267,7 +267,7 @@ def _update_io(voc, iph, io, rs, rsh, nnsvth):
     .. [1] PVLib MATLAB https://github.com/sandialabs/MATLAB_PV_LIB
     .. [2] C. Hansen, Parameter Estimation for Single Diode Models of
        Photovoltaic Modules, Sandia National Laboratories Report SAND2015-2065
-    .. [3] C. Hansen, Estimation of Parameteres for Single Diode Models using
+    .. [3] C. Hansen, Estimation of Parameters for Single Diode Models using
        Measured IV Curves, Proc. of the 39th IEEE PVSC, June 2013.
     """
 
diff --git a/pvlib/modelchain.py b/pvlib/modelchain.py
@@ -31,7 +31,7 @@
 # 'cell_temperature' overrides ModelChain.temperature_model and sets
 # ModelChain.cell_temperature to the data. If 'module_temperature' is provided,
 # overrides ModelChain.temperature_model with
-# pvlib.temperature.sapm_celL_from_module
+# pvlib.temperature.sapm_cell_from_module
 TEMPERATURE_KEYS = ('module_temperature', 'cell_temperature')
 
 DATA_KEYS = WEATHER_KEYS + POA_KEYS + TEMPERATURE_KEYS
@@ -46,7 +46,7 @@
 # for Flat-Plate Photovoltaic Arrays. SAND85-0330. Albuquerque, NM:
 # Sandia National Laboratories. Accessed September 3, 2013:
 # http://prod.sandia.gov/techlib/access-control.cgi/1985/850330.pdf
-# pvlib python does not implement that model, so use the SAPM instead.
+# pvlib-python does not implement that model, so it uses the SAPM instead.
 PVWATTS_CONFIG = dict(
     dc_model='pvwatts', ac_model='pvwatts', losses_model='pvwatts',
     transposition_model='perez', aoi_model='physical',
@@ -84,7 +84,7 @@ def get_orientation(strategy, **kwargs):
         surface_tilt = 0
     else:
         raise ValueError('invalid orientation strategy. strategy must '
-                         'be one of south_at_latitude, flat,')
+                         'be one of south_at_latitude_tilt, flat,')
 
     return surface_tilt, surface_azimuth
 
@@ -162,8 +162,8 @@ class ModelChainResult:
     # per DC array information
     total_irrad: Optional[PerArray[pd.DataFrame]] = field(default=None)
     """ DataFrame (or tuple of DataFrame, one for each array) containing
-    columns ``'poa_global'``, ``'poa_direct'`` ``'poa_diffuse'``,
-    ``poa_sky_diffuse'``, ``'poa_ground_diffuse'`` (W/m2); see
+    columns ``'poa_global'``, ``'poa_direct'``, ``'poa_diffuse'``,
+    ``poa_sky_diffuse'``, and ``'poa_ground_diffuse'`` (Wm⁻²); see
     :py:func:`~pvlib.irradiance.get_total_irradiance` for details.
     """
 
@@ -190,12 +190,12 @@ class ModelChainResult:
 
     cell_temperature: Optional[PerArray[pd.Series]] = field(default=None)
     """Series (or tuple of Series, one for each array) containing cell
-    temperature (C).
+    temperature (°C).
     """
 
     effective_irradiance: Optional[PerArray[pd.Series]] = field(default=None)
     """Series (or tuple of Series, one for each array) containing effective
-    irradiance (W/m2) which is total plane-of-array irradiance adjusted for
+    irradiance (Wm⁻²) which is total plane-of-array irradiance adjusted for
     reflections and spectral content.
     """
 
@@ -215,12 +215,12 @@ class ModelChainResult:
 
     dc_ohmic_losses: Optional[PerArray[pd.Series]] = field(default=None)
     """Series (or tuple of Series, one for each array) containing DC ohmic
-    loss (W) calculated by ``ModelChain.dc_ohmic_model``.
+    losses (W) calculated by ``ModelChain.dc_ohmic_model``.
     """
 
     # copies of input data, for user convenience
     weather: Optional[PerArray[pd.DataFrame]] = None
-    """DataFrame (or tuple of DataFrame, one for each array) contains a
+    """DataFrame (or tuple of DataFrame, one for each array) containing a
     copy of the input weather data.
     """
 
@@ -806,7 +806,7 @@ def infer_aoi_model(self):
                              'system.arrays[i].module_parameters. Check that '
                              'the module_parameters for all Arrays in '
                              'system.arrays contain parameters for the '
-                             'physical, aoi, ashrae, martin_ruiz or interp '
+                             'physical, sapm, ashrae, martin_ruiz or interp '
                              'model; explicitly set the model with the '
                              'aoi_model kwarg; or set aoi_model="no_loss".')
 
diff --git a/pvlib/singlediode.py b/pvlib/singlediode.py
@@ -696,27 +696,34 @@ def _lambertw_v_from_i(current, photocurrent, saturation_current,
 
     # Only compute using LambertW if there are cases with Gsh>0
     if np.any(idx_p):
+
+        # use only the relevant subset for what follows
+        I = I[idx_p]
+        IL = IL[idx_p]
+        I0 = I0[idx_p]
+        Rs = Rs[idx_p]
+        Gsh = Gsh[idx_p]
+        a = a[idx_p]
+
         # LambertW argument, cannot be float128, may overflow to np.inf
         # overflow is explicitly handled below, so ignore warnings here
         with np.errstate(over='ignore'):
-            argW = (I0[idx_p] / (Gsh[idx_p] * a[idx_p]) *
-                    np.exp((-I[idx_p] + IL[idx_p] + I0[idx_p]) /
-                           (Gsh[idx_p] * a[idx_p])))
+            argW = I0 / (Gsh * a) * np.exp((-I + IL + I0) / (Gsh * a))
 
         # lambertw typically returns complex value with zero imaginary part
         # may overflow to np.inf
         lambertwterm = lambertw(argW).real
 
         # Record indices where lambertw input overflowed output
-        idx_inf = np.logical_not(np.isfinite(lambertwterm))
+        idx_inf = np.isinf(lambertwterm)
 
         # Only re-compute LambertW if it overflowed
         if np.any(idx_inf):
             # Calculate using log(argW) in case argW is really big
-            logargW = (np.log(I0[idx_p]) - np.log(Gsh[idx_p]) -
-                       np.log(a[idx_p]) +
-                       (-I[idx_p] + IL[idx_p] + I0[idx_p]) /
-                       (Gsh[idx_p] * a[idx_p]))[idx_inf]
+            logargW = (np.log(I0[idx_inf]) - np.log(Gsh[idx_inf]) -
+                       np.log(a[idx_inf]) +
+                       (-I[idx_inf] + IL[idx_inf] + I0[idx_inf]) /
+                       (Gsh[idx_inf] * a[idx_inf]))
 
             # Three iterations of Newton-Raphson method to solve
             #  w+log(w)=logargW. The initial guess is w=logargW. Where direct
@@ -730,8 +737,7 @@ def _lambertw_v_from_i(current, photocurrent, saturation_current,
         # Eqn. 3 in Jain and Kapoor, 2004
         #  V = -I*(Rs + Rsh) + IL*Rsh - a*lambertwterm + I0*Rsh
         # Recast in terms of Gsh=1/Rsh for better numerical stability.
-        V[idx_p] = (IL[idx_p] + I0[idx_p] - I[idx_p]) / Gsh[idx_p] - \
-            I[idx_p] * Rs[idx_p] - a[idx_p] * lambertwterm
+        V[idx_p] = (IL + I0 - I) / Gsh - I * Rs - a * lambertwterm
 
     if output_is_scalar:
         return V.item()
diff --git a/pvlib/tracking.py b/pvlib/tracking.py
@@ -4,9 +4,14 @@
 from pvlib.tools import cosd, sind, tand, acosd, asind
 from pvlib import irradiance
 from pvlib import shading
+from pvlib._deprecation import renamed_kwarg_warning
 
 
-def singleaxis(apparent_zenith, apparent_azimuth,
+@renamed_kwarg_warning(
+    since='0.13.1',
+    old_param_name='apparent_azimuth',
+    new_param_name='solar_azimuth')
+def singleaxis(apparent_zenith, solar_azimuth,
                axis_tilt=0, axis_azimuth=0, max_angle=90,
                backtrack=True, gcr=2.0/7.0, cross_axis_tilt=0):
     """
@@ -33,7 +38,7 @@ def singleaxis(apparent_zenith, apparent_azimuth,
     apparent_zenith : float, 1d array, or Series
         Solar apparent zenith angles in decimal degrees.
 
-    apparent_azimuth : float, 1d array, or Series
+    solar_azimuth : float, 1d array, or Series
         Solar apparent azimuth angles in decimal degrees.
 
     axis_tilt : float, default 0
@@ -123,10 +128,10 @@ def singleaxis(apparent_zenith, apparent_azimuth,
         index = None
 
     # convert scalars to arrays
-    apparent_azimuth = np.atleast_1d(apparent_azimuth)
+    solar_azimuth = np.atleast_1d(solar_azimuth)
     apparent_zenith = np.atleast_1d(apparent_zenith)
 
-    if apparent_azimuth.ndim > 1 or apparent_zenith.ndim > 1:
+    if solar_azimuth.ndim > 1 or apparent_zenith.ndim > 1:
         raise ValueError('Input dimensions must not exceed 1')
 
     # The ideal tracking angle, omega_ideal, is the rotation to place the sun
@@ -142,7 +147,7 @@ def singleaxis(apparent_zenith, apparent_azimuth,
         axis_tilt=axis_tilt,
         axis_azimuth=axis_azimuth,
         solar_zenith=apparent_zenith,
-        solar_azimuth=apparent_azimuth,
+        solar_azimuth=solar_azimuth,
     )
 
     # filter for sun above panel horizon
@@ -191,7 +196,7 @@ def singleaxis(apparent_zenith, apparent_azimuth,
     surface_tilt = surface['surface_tilt']
     surface_azimuth = surface['surface_azimuth']
     aoi = irradiance.aoi(surface_tilt, surface_azimuth,
-                         apparent_zenith, apparent_azimuth)
+                         apparent_zenith, solar_azimuth)
 
     # Bundle DataFrame for return values and filter for sun below horizon.
     out = {'tracker_theta': tracker_theta, 'aoi': aoi,
diff --git a/tests/ivtools/sdm/test__fit_desoto_pvsyst_sandia.py b/tests/ivtools/sdm/test__fit_desoto_pvsyst_sandia.py
