Implement ANTS-2D bifacial irradiance model by kandersolar · Pull Request #2740 · pvlib/pvlib-python

kandersolar · 2026-04-21T19:52:53Z

~~[ ] Closes #xxxx~~
I am familiar with the contributing guidelines
I attest that all AI-generated material has been vetted for accuracy and is in compliance with the pvlib license
Tests added
Updates entries in docs/sphinx/source/reference for API changes.
Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for all changes. Includes link to the GitHub Issue with :issue:`num` or this Pull Request with :pull:`num`. Includes contributor name and/or GitHub username (link with :ghuser:`user`).
New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
Pull request is nearly complete and ready for detailed review.
Maintainer: Appropriate GitHub Labels (including remote-data) and Milestone are assigned to the Pull Request and linked Issue.

@AdamRJensen, @cwhanse, and I have a paper describing a new bifacial irradiance model called ANTS-2D. It is similar to pvlib's infinite_sheds model, but extended to allow:

a discretized module surface (for, e.g., cell-level irradiance values)
a discretized ground surface, with variable albedo
sloped terrain, in the fashion of pvlib's existing functionality in that area
the Perez transposition model, in addition to Hay-Davies and isotropic
computation of ground-level irradiance (for agriPV)
fast computation by using analytical integrated view factors instead of burdensome numerical integrals

Details available open-access here: https://doi.org/10.1109/JPHOTOV.2026.3677506

This PR is rather large. To summarize:

Add g0 and g1 parameters to the view factor functions in pvlib.bifacial.utils. These are analogous to x0 and x1 in vf_row_sky_2d_integ and extend the functions to subset the ground surface.
Change vf_ground_sky_2d_integ to use Hottel's crossed-string rule instead of burdensome numerical integration. This makes the npoints and vectorize parameters unnecessary.
Change some signatures in pvlib.bifacial.utils to be cleaner with the new calculations.
Minor edits in pvlib.bifacial.infinite_sheds to accommodate the utils changes
Create pvlib.bifacial.ant2d, which houses the model itself and uses the new utils functionality.

Let me know if it would help reviewers to split it up and review separate PRs, starting with utils.

echedey-ls

Some first impressions; also, you may want to link to it in other bifacial "See also" sections.

echedey-ls · 2026-05-03T22:45:56Z

-def vf_ground_sky_2d_integ(surface_tilt, gcr, height, pitch, max_rows=10,
-                           npoints=100, vectorize=False):
+@renamed_kwarg_warning("0.15.2", "surface_tilt", "tracker_rotation")
+def vf_ground_sky_2d_integ(tracker_rotation, gcr, height, pitch, g0=0, g1=1,


Suggested change

def vf_ground_sky_2d_integ(tracker_rotation, gcr, height, pitch, g0=0, g1=1,

def vf_ground_sky_2d_integ(tracker_rotation, gcr, height, pitch, *, g0=0, g1=1,

The rationale is that previous versions assume this call signature

vf_ground_sky_2d_integ(0, 0.5, 2, 4, 20, 200), where max_rows=20 and npoints=200

This wouldn't fail in the new version [1], where values g0 and g1 would take 20 and 200 respectively.

[1] At this branch

>>> import pvlib >>> pvlib.bifacial.utils.vf_ground_sky_2d_integ(0, 0.5, 2, 4, 20, 200) array(1.14662412e-05)

[2] On main

array([0.49984351])

echedey-ls · 2026-05-03T22:55:43Z

+def vf_row_ground_2d_integ(surface_tilt, gcr, height=None, pitch=None,
+                           x0=0, x1=1, g0=0, g1=1, max_rows=20):


I'd say this one is also subject to the problem described in previous comment

cwhanse

I'm OK reviewing the whole PR, if we can do it in a sequence of smaller review bites.

cwhanse · 2026-05-05T22:31:33Z

+* 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


I think a comment here about "this makes bifacial.infinite_sheds faster would be appreciated.

cwhanse · 2026-05-05T22:42:10Z

+        Projected solar zenith angle, defined around the same axis as
+        ``tracker_rotation``. [degree].


I don't understand this definition. A vector can be projected onto a plane or another vector. An angle is formed by two vectors. "around" suggests an orientation of a vector.

tan_phi was defined in the docstrings for _solar_project_tangent as

Tangent of the angle between the zenith vector and the sun vector projected to the plane defined by the zenith vector and surface_azimuth.

So I would expect phi to be the angle of the sun vector projected to a plane formed by....

Since phi isn't clear, tracker_rotation becomes unclear also.

cwhanse · 2026-05-05T22:43:24Z

        spacing (pitch). [unitless]
-    max_zenith : numeric, default 87
+    height : float, optional
+        Height of the center point of the row above the ground; must be in the


Center point means the center of the row slant length? If that's correct I'd make it

Height above ground of the center point of the row slant length; must be in the

cwhanse · 2026-05-05T22:44:10Z

+        Distance between two rows; must be in the same units as ``height``.
+        Required if ``g0`` is not zero or ``g1`` is not one.
+    g0 : numeric, default 0
+        Position on the ground surface, as a fraction of the row-to-row


Suggested change

Position on the ground surface, as a fraction of the row-to-row

Left position on the ground surface, as a fraction of the row-to-row

g0 is the left position on the ground, I think.

cwhanse · 2026-05-05T22:44:31Z

+        spacing. ``g0=0`` corresponds to ground underneath the middle of the
+        left row. ``g0`` should be less than ``g1``. [unitless]
+    g1 : numeric, default 1
+        Position on the ground surface, as a fraction of the row-to-row


Suggested change

Position on the ground surface, as a fraction of the row-to-row

Right position on the ground surface, as a fraction of the row-to-row

cwhanse · 2026-05-05T22:45:01Z

+        Required if ``g0`` is not zero or ``g1`` is not one.
+    g0 : numeric, default 0
+        Position on the ground surface, as a fraction of the row-to-row
+        spacing. ``g0=0`` corresponds to ground underneath the middle of the


Suggested change

spacing. ``g0=0`` corresponds to ground underneath the middle of the

spacing. ``g0=0`` corresponds to ground underneath the center of the

cwhanse · 2026-05-05T22:45:11Z

+        left row. ``g0`` should be less than ``g1``. [unitless]
+    g1 : numeric, default 1
+        Position on the ground surface, as a fraction of the row-to-row
+        spacing. ``g1=1`` corresponds to ground underneath the middle of the


Suggested change

spacing. ``g1=1`` corresponds to ground underneath the middle of the

spacing. ``g1=1`` corresponds to ground underneath the center of the

cwhanse · 2026-05-05T22:46:07Z

+        Maximum number of rows to consider on either side of the current
+        row. [unitless]


Suggested change

Maximum number of rows to consider on either side of the current

row. [unitless]

Maximum number of rows to consider on either side of the left and right

rows. [unitless]

Related to the [max_rows, max_rows+1] comment below.

cwhanse · 2026-05-05T22:53:38Z

+    # TODO seems like this should be np.arange(-max_rows, max_rows+1)?
+    # see GH #1867
+    k = np.arange(-max_rows, max_rows)[:, np.newaxis, np.newaxis]


I would do (-max_rows, max_rows + 1) or is this a breaking change needing deprecation?

cwhanse · 2026-05-05T22:55:39Z

+        same units as ``pitch``.  Required if ``g0`` is not zero or ``g1`` is
+        not one.
+    pitch : float, optional
+        Distance between two rows; must be in the same units as ``height``.


Suggested change

Distance between two rows; must be in the same units as ``height``.

Distance between centers of two rows; must be in the same units as ``height``.

"centers" is arbritrary. I think we want to avoid the confusion that the distance is the gap between the right edge of left row, and the left edge of right row.

kandersolar added 30 commits September 29, 2025 14:15

ants2d and new VF code

d6d6f31

remove some cruft

99a7a81

add tests for ants2d._shaded_fraction

a6f22bb

refactoring and more tests

02686aa

tests for _apply_ground_slope

034efd9

tests for _apply_sky_diffuse_model

4748915

fix return shape and tests for vf_row_ground_2d_integ

d2bf3ad

fix return shape and tests for vf_row_sky_2d_integ

405649b

major docstring cleanup

7dd6853

standardize to "back" instead of "rear"

505d8d4

shape fixes, pandas out

8811daa

bugfix in unshaded ground fraction

0907682

add several tests for main function

8c792ec

test updates

9d28b75

better return type logic; more get_irradiance tests

2331023

expose max_rows, more get_irradiance tests

56fe82b

fix issue with horizontal array and large max_rows

920ec30

fix unshaded_ground_fraction for horizontal special case

403c0a4

fix row->ground VF edge case

24c8f32

switch default model from isotropic to perez

06f2a97

add hardcoded regression test

69105fd

alphabetize module imports

eaa8fd1

docstring work

98d1664

utils functions: make height and pitch optional

784877f

get infinite_sheds working again

2cbfb0d

polishing

7927422

fix output when surface angle is scalar but irrad is array

52d4fc2

simplify numpy import

39663ea

add option to return irradiance incident on ground surface

5a650e4

more tests for ground irradiance

28480f7

kandersolar added 5 commits December 1, 2025 18:41

one more test

0fa4bc9

use assert_allclose, not assert np.isclose

258d5a6

allow specifying custom row/ground subsets

015500d

lint

2b5750a

Merge remote-tracking branch 'upstream/main' into ants2d

6e23585

kandersolar added this to the v0.15.2 milestone Apr 21, 2026

kandersolar added the enhancement label Apr 21, 2026

use poa_ for return_components=True after pvlib#2627

cf1ce33

kandersolar mentioned this pull request Apr 23, 2026

Use Hottel's method for bifacial.utils.*_integ functions #1865

Closed

8 tasks

kandersolar added 10 commits April 24, 2026 14:41

misc cleanup

92a95b2

fix squeeze bug

e651baf

deprecate npoints, vectorize

c8be126

fix deprecation version

69eaf67

lint

485eb0c

docstring cleanup

e4c0c51

whatsnew entries

30257a7

fix broken gallery example

a36841d

add reference docs entry and user guide description

611f9da

add test to cover untested branch

e81e250

kandersolar marked this pull request as ready for review April 30, 2026 15:36

echedey-ls reviewed May 4, 2026

View reviewed changes

cwhanse reviewed May 5, 2026

View reviewed changes

	def vf_ground_sky_2d_integ(tracker_rotation, gcr, height, pitch, g0=0, g1=1,
	def vf_ground_sky_2d_integ(tracker_rotation, gcr, height, pitch, *, g0=0, g1=1,

		def vf_row_ground_2d_integ(surface_tilt, gcr, height=None, pitch=None,
		x0=0, x1=1, g0=0, g1=1, max_rows=20):

		Projected solar zenith angle, defined around the same axis as
		``tracker_rotation``. [degree].

	Position on the ground surface, as a fraction of the row-to-row
	Left position on the ground surface, as a fraction of the row-to-row

	Position on the ground surface, as a fraction of the row-to-row
	Right position on the ground surface, as a fraction of the row-to-row

	spacing. ``g0=0`` corresponds to ground underneath the middle of the
	spacing. ``g0=0`` corresponds to ground underneath the center of the

	spacing. ``g1=1`` corresponds to ground underneath the middle of the
	spacing. ``g1=1`` corresponds to ground underneath the center of the

		Maximum number of rows to consider on either side of the current
		row. [unitless]

	Distance between two rows; must be in the same units as ``height``.
	Distance between centers of two rows; must be in the same units as ``height``.

Conversation

kandersolar commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

echedey-ls left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cwhanse left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kandersolar commented Apr 21, 2026 •

edited

Loading