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.

cwhanse

Review of file ants2d.py. OK with file infinite_sheds.py.

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

…into ants2d

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

cwhanse

Thorough tests!

williamhobbs · 2026-07-13T17:50:11Z

I think the documentation for ants2d.get_irradiance needs clarification on how to model fixed-tilt systems. I.e., how to convert tilt angle and azimuth into tracker_rotation and axis_azimuth (and similar for axis_tilt and cross_axis_slope).

williamhobbs · 2026-07-13T18:30:54Z

In pvlib.irradiance.get_total_irradiance, the input for model for Perez-Driesse is perez-driesse, but here it is perez_driesse. I suggest changing it to perez-driesse for consistency, unless there is a reason to do it differently here.

williamhobbs · 2026-07-13T18:43:13Z

+        (``n_ground_segments``, ``len(tracker_rotation)``). [unitless]
+    model : str, default 'perez'
+        Irradiance model - can be one of 'isotropic', 'haydavies', 'perez',
+        or 'perez_driesse'.


Suggested change

or 'perez_driesse'.

or 'perez-driesse'.

williamhobbs · 2026-07-13T18:43:45Z

+        or 'perez_driesse'.
+    dni_extra : numeric, optional
+        Extraterrestrial direct normal irradiance. Required when
+        ``model='haydavies'``, ``model='perez'``, or ``model='perez_driese'``.


Suggested change

``model='haydavies'``, ``model='perez'``, or ``model='perez_driese'``.

``model='haydavies'``, ``model='perez'``, or ``model='perez-driesse'``.

note that there was also a type here

williamhobbs · 2026-07-13T18:44:12Z

+        Computed from the datetime index of the inputs if not provided. [Wm⁻²]
+    airmass : numeric, optional
+        Relative airmass. Required when ``model='perez'`` or
+        ``model='perez_driese'``. Computed from ``solar_zenith`` if needed.


Suggested change

``model='perez_driese'``. Computed from ``solar_zenith`` if needed.

``model='perez-driesse'``. Computed from ``solar_zenith`` if needed.

note that there was also a type here

williamhobbs · 2026-07-13T18:44:48Z

+
+    # Section II.C.2
+
+    if model in ['haydavies', 'perez', 'perez_driesse']:


Suggested change

if model in ['haydavies', 'perez', 'perez_driesse']:

if model in ['haydavies', 'perez', 'perez-driesse']:

williamhobbs · 2026-07-13T18:45:15Z

+            diffuse_model_func = haydavies
+            extra_kwargs = {}
+
+        elif model in ['perez', 'perez_driesse']:


Suggested change

elif model in ['perez', 'perez_driesse']:

elif model in ['perez', 'perez-driesse']:

williamhobbs · 2026-07-13T18:46:05Z

+
+    Notes
+    -----
+    - ``model='perez_driesse'`` was not evaluated in [1]_ and is included


Suggested change

- ``model='perez_driesse'`` was not evaluated in [1]_ and is included

- ``model='perez-driesse'`` was not evaluated in [1]_ and is included

williamhobbs · 2026-07-13T18:46:31Z

+
+    # preparation steps
+
+    if airmass is None and model in ['perez', 'perez_driesse']:


Suggested change

if airmass is None and model in ['perez', 'perez_driesse']:

if airmass is None and model in ['perez', 'perez-driesse']:

williamhobbs · 2026-07-13T18:46:53Z

+        airmass = get_relative_airmass(solar_zenith)
+
+    if (dni_extra is None and
+            model in ['perez', 'perez_driesse', 'haydavies'] and


Suggested change

model in ['perez', 'perez_driesse', 'haydavies'] and

model in ['perez', 'perez-driesse', 'haydavies'] and

williamhobbs · 2026-07-14T12:55:31Z

Could it be worthwhile to return unshaded irradiance, e.g., poa_front_direct_unshaded? It would help with some types of shade loss models [1, 2] and with general loss accounting (e.g., if someone wanted to make waterfall/Sankey charts).

I haven't fully thought through trade-offs and alternatives yet, but I thought it was worth bringing up.

[1] Anderson, Kevin. 2020. Maximizing Yield with Improved Single-Axis Backtracking on Cross-Axis Slopes: Preprint. Golden, CO: National Renewable Energy Laboratory. NREL/CP-5K00-76023. https://www.nlr.gov/docs/fy20osti/76023.pdf

[2] W. Hobbs, K. Anderson, M. Mikofski, and M. Ghiz, “An approach to modeling linear and non-linear self-shading losses with PVlib,” in PV Perform. Model. Collaborative Workshop, Sandia Nat. Lab., May 2024. [Online]. Available: https://www.sandia.gov/app/uploads/sites/243/dlm_uploads/2024/05/2024_PVPMC_hobbs_pvlib_self-shade.pdf

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

cwhanse reviewed Jun 17, 2026

View reviewed changes

Comment thread pvlib/bifacial/ants2d.py

Comment thread pvlib/bifacial/ants2d.py Outdated

Comment thread pvlib/bifacial/ants2d.py Outdated

Comment thread pvlib/bifacial/ants2d.py Outdated

Comment thread pvlib/bifacial/utils.py Outdated

cwhanse reviewed Jun 17, 2026

View reviewed changes

Comment thread pvlib/bifacial/ants2d.py

Comment thread pvlib/bifacial/ants2d.py Outdated

Comment thread pvlib/bifacial/ants2d.py

Comment thread pvlib/bifacial/ants2d.py

kandersolar and others added 7 commits June 17, 2026 11:29

Apply suggestions from code review

ffb221d

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

clarifications from review by @cwhanse

d47bc70

Update pvlib/bifacial/ants2d.py

7062a29

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

Merge branch 'ants2d' of https://github.com/kandersolar/pvlib-python …

fcda25e

…into ants2d

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

4271121

transfer whatsnew entries to 0.15.3

944c513

fix bad merge

f8575f9

cwhanse reviewed Jun 17, 2026

View reviewed changes

Comment thread pvlib/bifacial/utils.py

kandersolar added 2 commits June 17, 2026 13:37

compute airmass, dni_extra as needed

ba382ab

clarifying comments

fdefe63

cwhanse reviewed Jun 17, 2026

View reviewed changes

Comment thread pvlib/bifacial/utils.py Outdated

Comment thread pvlib/bifacial/utils.py

Comment thread pvlib/bifacial/utils.py Outdated

Comment thread pvlib/bifacial/utils.py Outdated

kandersolar and others added 4 commits June 17, 2026 13:40

lint

2a7f57e

apply suggested edit

02bc88c

Apply suggestions from code review

f7c9830

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

lint

55056de

cwhanse approved these changes Jun 17, 2026

View reviewed changes

Comment thread tests/bifacial/test_ants2d.py Outdated

address comment nit

80052b8

williamhobbs reviewed Jul 13, 2026

View reviewed changes

	``model='haydavies'``, ``model='perez'``, or ``model='perez_driese'``.
	``model='haydavies'``, ``model='perez'``, or ``model='perez-driesse'``.

	``model='perez_driese'``. Computed from ``solar_zenith`` if needed.
	``model='perez-driesse'``. Computed from ``solar_zenith`` if needed.


		# Section II.C.2

		if model in ['haydavies', 'perez', 'perez_driesse']:

	elif model in ['perez', 'perez_driesse']:
	elif model in ['perez', 'perez-driesse']:

	- ``model='perez_driesse'`` was not evaluated in [1]_ and is included
	- ``model='perez-driesse'`` was not evaluated in [1]_ and is included


		# preparation steps

		if airmass is None and model in ['perez', 'perez_driesse']:

	model in ['perez', 'perez_driesse', 'haydavies'] and
	model in ['perez', 'perez-driesse', 'haydavies'] and

Uh oh!

Conversation

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cwhanse left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cwhanse left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

williamhobbs commented Jul 13, 2026

Uh oh!

williamhobbs commented Jul 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

williamhobbs Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

williamhobbs commented Jul 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kandersolar commented Apr 21, 2026 •

edited

Loading

williamhobbs Jul 13, 2026 •

edited

Loading