Skip to content

Implement ANTS-2D bifacial irradiance model#2740

Open
kandersolar wants to merge 74 commits into
pvlib:mainfrom
kandersolar:ants2d
Open

Implement ANTS-2D bifacial irradiance model#2740
kandersolar wants to merge 74 commits into
pvlib:mainfrom
kandersolar:ants2d

Conversation

@kandersolar

@kandersolar kandersolar commented Apr 21, 2026

Copy link
Copy Markdown
Member
  • [ ] 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.

@kandersolar kandersolar modified the milestones: v0.15.2, v0.15.3 Jun 9, 2026
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 cwhanse left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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
Comment thread pvlib/bifacial/utils.py
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

@cwhanse cwhanse left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thorough tests!

Comment thread tests/bifacial/test_ants2d.py Outdated
assert 0 == ants2d._shaded_fraction(10, 20, 0.5)
assert 0 == ants2d._shaded_fraction(-10, -20, 0.5)

# sun behind the modules (AOI > 90)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very minor nit: "sun behind the modules" I think I would comment this case as "module facing away from the sun" since the function being tested returns "fraction...shaded from direct irradiance by the row in front toward the sun." It is implied that _shaded_fraction is specific to one face of a module, which (in this case) is face pointed away from the sun.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants