Implement ANTS-2D bifacial irradiance model (#2740)

* ants2d and new VF code

* remove some cruft

* add tests for ants2d._shaded_fraction

* refactoring and more tests

* tests for _apply_ground_slope

* tests for _apply_sky_diffuse_model

* fix return shape and tests for vf_row_ground_2d_integ

* fix return shape and tests for vf_row_sky_2d_integ

* major docstring cleanup

* standardize to "back" instead of "rear"

* shape fixes, pandas out

* bugfix in unshaded ground fraction

* add several tests for main function

* test updates

* better return type logic; more get_irradiance tests

* expose max_rows, more get_irradiance tests

* fix issue with horizontal array and large max_rows

* fix unshaded_ground_fraction for horizontal special case

* fix row->ground VF edge case

* switch default model from isotropic to perez

* add hardcoded regression test

* alphabetize module imports

* docstring work

* utils functions: make height and pitch optional

* get infinite_sheds working again

* polishing

* fix output when surface angle is scalar but irrad is array

* simplify numpy import

* add option to return irradiance incident on ground surface

* more tests for ground irradiance

* one more test

* use `assert_allclose`, not `assert np.isclose`

* allow specifying custom row/ground subsets

* lint

* use `poa_` for `return_components=True` after #2627

* misc cleanup

* fix squeeze bug

* deprecate `npoints`, `vectorize`

* fix deprecation version

* lint

* docstring cleanup

* whatsnew entries

* fix broken gallery example

* add `reference` docs entry and user guide description

* add test to cover untested branch

* feedback from review

Co-Authored-By: Cliff Hansen <5393711+cwhanse@users.noreply.github.com>

* Update pvlib/bifacial/utils.py

Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

* adopt new description for `phi`

* Update pvlib/bifacial/utils.py

Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

* changes from review

* allow perez_driesse

* add reference to utils functions

* move g0, g1 to end of function signatures

* fix whatsnew merge

* update tests for #1867

* Apply suggestions from code review

Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

* clarifications from review by @cwhanse

* Update pvlib/bifacial/ants2d.py

Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

* transfer whatsnew entries to 0.15.3

* fix bad merge

* compute airmass, dni_extra as needed

* clarifying comments

* lint

* apply suggested edit

* Apply suggestions from code review

Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>

* lint

* address comment nit

* Apply suggestions from code review

Co-authored-by: Will Hobbs <45701090+williamhobbs@users.noreply.github.com>

* update tests per review

* add notes on fixed-tilt

* fix bad whatsnew auto-merge

* tweaks to user's guide page

* changes from review

* Update pvlib/bifacial/utils.py

Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com>

* Update pvlib/bifacial/utils.py

Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com>

* Update pvlib/bifacial/ants2d.py

Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com>

* Update pvlib/bifacial/ants2d.py

Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com>

* lint

---------

Co-authored-by: Cliff Hansen <5393711+cwhanse@users.noreply.github.com>
Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>
Co-authored-by: Will Hobbs <45701090+williamhobbs@users.noreply.github.com>
Co-authored-by: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com>

Author: 4 people

docs/examples/agrivoltaics/plot_agrivoltaics_ground_irradiance.py

@@ -134,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/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,6 +47,14 @@ 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

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(