Merge branch 'main' into merra2

Author: kandersolar

docs/examples/agrivoltaics/plot_agrivoltaics_ground_irradiance.py

@@ -13,17 +13,15 @@
 # is referred to :doi:`10.69766/XAEU5008`.
 #
 # This gallery example is based on an actual AgriPV plant, namely
-# European Energy's `Flakkebjerg AgriPV site
-# <https://europeanenergy.com/2023/12/20/using-the-same-land-twice-at-european-\
-# energys-flakkebjerg-solar-park/>`_.
+# European Energy's Flakkebjerg AgriPV site.
 #
 # The first steps are to define the plant location and to calculate solar
 # position and clearsky irradiance for a single day as an example.
 #
 # .. figure:: ../../_images/agrivoltaics_system.jpg
 #    :align: center
 #    :width: 75%
-#    :alt: Photo of an agriPV system
+#    :alt: Photo of the Flakkebjerg agriPV system
 #
 #    Photo of an agriPV system.
 #    *Source: Adam R. Jensen*
@@ -136,17 +134,21 @@
 # (i.e., receives DNI).
 
 vf_ground_sky = pvlib.bifacial.utils.vf_ground_sky_2d_integ(
-    surface_tilt=tracking_orientations['surface_tilt'],
+    tracker_rotation=tracking_orientations['tracker_theta'],
     gcr=gcr,
     height=height,
     pitch=pitch,
 )
 
-unshaded_ground_fraction = pvlib.bifacial.utils._unshaded_ground_fraction(
-    surface_tilt=tracking_orientations['surface_tilt'],
-    surface_azimuth=tracking_orientations['surface_azimuth'],
+phi = pvlib.shading.projected_solar_zenith_angle(
     solar_zenith=solpos['apparent_zenith'],
     solar_azimuth=solpos['azimuth'],
+    axis_tilt=0,
+    axis_azimuth=axis_azimuth,
+)
+unshaded_ground_fraction = pvlib.bifacial.utils._unshaded_ground_fraction(
+    tracker_rotation=tracking_orientations['tracker_theta'],
+    phi=phi,
     gcr=gcr,
 )
 

docs/sphinx/source/reference/bifacial.rst

@@ -11,6 +11,7 @@ Functions for calculating front and back surface irradiance
    bifacial.pvfactors.pvfactors_timeseries
    bifacial.infinite_sheds.get_irradiance
    bifacial.infinite_sheds.get_irradiance_poa
+   bifacial.ants2d.get_irradiance
 
 Loss models that are specific to bifacial PV systems
 

docs/sphinx/source/user_guide/getting_started/installation.rst

@@ -138,7 +138,7 @@ Follow these steps to obtain the library using git/GitHub:
 Please see GitHub's
 `Forking Projects <https://guides.github.com/activities/forking/>`_,
 `Fork A Repo <https://help.github.com/articles/fork-a-repo/>`_,
-and the `git-scm <https://git-scm.com/documentation>`_ for
+and the `git-scm <https://git-scm.com/docs>`_ for
 more details.
 
 .. _setupenvironment:

docs/sphinx/source/user_guide/modeling_topics/bifacial.rst

@@ -12,7 +12,7 @@ the primary source of light. The primary challenge in modeling a PV system
 with bifacial modules is estimating the irradiance on the front and back
 surfaces.
 
-pvlib-python provides two groups of functions for estimating front and back
+pvlib-python provides three groups of functions for estimating front and back
 irradiance:
 
 1. a wrapper for convenient use of the pvfactors model:
@@ -22,6 +22,7 @@ irradiance:
 :py:func:`~pvlib.bifacial.infinite_sheds.get_irradiance`
 :py:func:`~pvlib.bifacial.infinite_sheds.get_irradiance_poa`
 
+3. the ANTS-2D bifacial model: :py:func:`~pvlib.bifacial.ants2d.get_irradiance`
 
 pvfactors
 ---------
@@ -50,7 +51,7 @@ after installation, Python code still accesses it as "pvfactors"
 Infinite Sheds
 --------------
 
-The "infinite sheds" model [1] is a 2-dimensional model of irradiance on the
+The "infinite sheds" model [1]_ is a 2-dimensional model of irradiance on the
 front and rear surfaces of a PV array. The model assumes that the array
 comprises parallel, equally spaced rows (sheds) and calculates irradiance in
 the middle of a shed which is far from the front and back rows of the array.
@@ -101,7 +102,7 @@ View factors from the ground to the sky are calculated at points spaced along
 a one-dimensional axis on the ground, with the origin under the center of a
 row and the positive direction toward the right. The positive direction is
 considered to be towards the "front" of the array. Array height differs in this
-code from the description in [1], where array height is described at the row's
+code from the description in [1]_, where array height is described at the row's
 lower edge.
 
 If ``model='isotropic'`` (the default), ``dhi`` is assumed to be isotropically
@@ -111,9 +112,23 @@ the input ``dhi`` is decomposed into circumsolar and isotropic components using
 :py:func:`~pvlib.irradiance.haydavies`, with the circumsolar component treated
 as additional ``dni`` for transposition and shading purposes.
 
-This model is influenced by the 2D model published by Marion, *et al.* in [2].
+This model is influenced by the 2D model published by Marion, *et al.* in [2]_.
 
 
+ANTS-2D
+-------
+
+The ANTS-2D model is a 2-D model similar to the Infinite Sheds and pvfactors
+models.  However, it has additional inputs to allow modeling of arrays on
+sloped terrain and ground surfaces with nonuniform albedo.  It partitions the
+module and ground surfaces into a user-specified number of segments to better
+capture irradiance nonuniformity effects.  It is also computationally efficient
+relative to models of comparable capability like pvfactors.  Finally, it can
+compute and return irradiance components at the ground level, which may be
+useful for agriPV modeling.
+
+For details, see :py:func:`~pvlib.bifacial.ants2d.get_irradiance` and Ref. [3]_.
+
 References
 ----------
 .. [1] Mikofski, M., Darawali, R., Hamer, M., Neubert, A., and Newmiller,
@@ -124,4 +139,7 @@ References
    Riley, D., Stein, J. and Hansen, C. "A Practical Irradiance Model for
    Bifacial PV Modules".2017 IEEE 44th Photovoltaic Specialists Conference
    (PVSC), 2017, pp. 1537-1543. doi: 10.1109/PVSC.2017.8366263
+.. [3] K. S. Anderson, A. R. Jensen, and C. W. Hansen, "A Bifacial View
+   Factor Model Considering Terrain Slope and Nonuniform Albedo,"
+   IEEE JPV, 2026. :doi:`10.1109/JPHOTOV.2026.3677506`
 

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

@@ -10,10 +10,23 @@ Breaking Changes
 
 Deprecations
 ~~~~~~~~~~~~
+* Parameters ``npoints`` and ``vectorize`` in the following functions
+  are now unnecessary and are deprecated (:pull:`2740`):
+
+  - :py:func:`pvlib.bifacial.infinite_sheds.get_irradiance`
+  - :py:func:`pvlib.bifacial.infinite_sheds.get_irradiance_poa`
+  - :py:func:`pvlib.bifacial.utils.vf_ground_sky_2d_integ`
+
+* Parameter ``surface_tilt`` is deprecated and renamed to ``tracker_rotation``
+  in :py:func:`pvlib.bifacial.utils.vf_ground_sky_2d_integ` (:pull:`2740`).
 * Deprecate non-polynomial interpolation options in :py:func:`pvlib.iam.interp` (:issue:`2394`, :pull:`2741`)
 
+
 Bug fixes
 ~~~~~~~~~
+* Fix asymmetry in how ``max_rows`` is interpreted in
+  :py:func:`~pvlib.bifacial.utils.vf_ground_sky_2d`. The difference
+  should be negligible for typical simulations. (:issue:`1867`, :pull:`2740`)
 * :py:func:`~pvlib.solarposition.sun_rise_set_transit_spa` now returns
   sunrise, sunset, and transit for the *local* calendar day of each input
   timestamp, restoring the behavior from before v0.11.1. Evening-local
@@ -34,13 +47,24 @@ Enhancements
   :py:func:`~pvlib.iotools.get_nsrdb_psm4_polar_tmy`.
   (:issue:`2639`, :pull:`2807`)
 * Ensure all timezones are available in all OSs. (:issue:`2795`, :pull:`2809`)
+* Implement the ANTS-2D bifacial irradiance model in
+  :py:func:`pvlib.bifacial.ants2d.get_irradiance`. (:pull:`2740`)
+* Add parameters ``g0`` and ``g1`` to allow segmented ground surfaces in
+  :py:func:`~pvlib.bifacial.utils.vf_ground_sky_2d_integ` and
+  :py:func:`~pvlib.bifacial.utils.vf_row_ground_2d_integ`. (:pull:`2740`)
+* Accelerate :py:func:`~pvlib.bifacial.utils.vf_ground_sky_2d_integ` by one or
+  two orders of magnitude. This also makes :py:mod:`pvlib.bifacial.infinite_sheds` faster.
+  (:pull:`2740`)
 
 
 Documentation
 ~~~~~~~~~~~~~
 * Fix broken link in GitHub Contributing tab. (:issue:`2628`, :pull:`2806`)
 * Fixed broken ``interval`` keyword argument in the ``oedi_9068`` gallery
   example; the correct parameter name is ``time_step``. (:issue:`2791`)
+* Fixed several broken/outdated links: NREL clear-sky and spectral data
+  pages, EnergyPlus documentation, git-scm.com, and a malformed Wikipedia
+  URL. (:issue:`2489`, :pull:`2818`)
 * Standardized diffuse component names and descriptions in the docstrings of
   multiple functions in :py:mod:`pvlib.irradiance`. (:pull:`2827`)
 

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

@@ -17,7 +17,9 @@ Breaking Changes
 
 Deprecations
 ~~~~~~~~~~~~
-
+* Deprecate :py:func:`pvlib.irradiance.king`.
+  Use other diffuse transposition models in :py:mod:`pvlib.irradiance` instead.
+  (:issue:`2636`, :pull:`2783`)
 
 Bug fixes
 ~~~~~~~~~
@@ -28,6 +30,9 @@ Bug fixes
 
 Enhancements
 ~~~~~~~~~~~~
+* Map beam horizontal irradiance to ``bhi`` when
+  :py:func:`~pvlib.iotools.get_era5` is called with ``map_variables=True``.
+  (:pull:`2819`)
 * Allow variables from multiple datasets to be requested at once in
   :py:func:`~pvlib.iotools.get_merra2`. (:pull:`2839`)
 

pvlib/bifacial/__init__.py

@@ -3,7 +3,9 @@
 """
 
 from pvlib._deprecation import deprecated
-from pvlib.bifacial import pvfactors, infinite_sheds, utils  # noqa: F401
+from pvlib.bifacial import (  # noqa: F401
+    ants2d, infinite_sheds, pvfactors, utils
+)
 from .loss_models import power_mismatch_deline  # noqa: F401
 
 pvfactors_timeseries = deprecated(