Skip to content

Clarify AOI-minimizing principle in tracking.singleaxis docstring - #2869

Open
chenyi6758-source wants to merge 3 commits into
pvlib:mainfrom
chenyi6758-source:docs/singleaxis-docstring-aoi
Open

chenyi6758-source wants to merge 3 commits into
pvlib:mainfrom
chenyi6758-source:docs/singleaxis-docstring-aoi

Conversation

@chenyi6758-source

@chenyi6758-source chenyi6758-source commented Sep 28, 2026 •

Copy link
Copy Markdown

The docstring for pvlib.tracking.singleaxis describes the coordinate system and rotation conventions in detail, but never states the underlying principle: the rotation angle is chosen to minimize the angle of incidence (AOI) of the sun's beam onto the panel, thereby maximizing the use of direct normal irradiance (DNI).

This PR adds that explanation to the docstring, including a note that backtracking adjusts the rotation away from the AOI-minimizing angle to avoid row-to-row shading. Also adds a whatsnew entry.

Closes #2314.

  • 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.

@github-actions

Copy link
Copy Markdown

Hey @chenyi6758-source! 🎉

Thanks for opening your first pull request! We appreciate your
contribution. Please ensure you have reviewed and understood the
contributing guidelines.

If AI is used for any portion of this PR, you must vet the content
for technical accuracy.

@kandersolar

Copy link
Copy Markdown
Member

@chenyi6758-source please edit the PR description to include the checklist from the PR template, and tick the items you are able to.

@chenyi6758-source

Copy link
Copy Markdown
Author

Done — checklist added to the PR description, with the applicable items ticked.

@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.

@chenyi6758-source you can add your GH tag to the contributors at the bottom of the whatsnew file.

Comment thread pvlib/tracking.py Outdated
Comment on lines 21 to 27
The rotation angle is chosen to minimize the angle of incidence (AOI) of
the sun's beam onto the panel, thereby maximizing the use of direct
normal irradiance (DNI). When backtracking is enabled, the rotation is
adjusted away from this AOI-minimizing angle to avoid row-to-row shading.

See [1]_ and [2]_ for details about the equations. Backtracking may be
specified, in which case a ground coverage ratio is required.

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.

Suggested change
The rotation angle is chosen to minimize the angle of incidence (AOI) of
the sun's beam onto the panel, thereby maximizing the use of direct
normal irradiance (DNI). When backtracking is enabled, the rotation is
adjusted away from this AOI-minimizing angle to avoid row-to-row shading.
See [1]_ and [2]_ for details about the equations. Backtracking may be
specified, in which case a ground coverage ratio is required.
The rotation angle is chosen to minimize the angle of incidence (AOI) of
the sun's beam onto the panel, thereby maximizing the use of direct
normal irradiance (DNI). Backtracking may be specified, in which case
a ground coverage ratio is required. When backtracking, the rotation is
adjusted away from the AOI-minimizing angle to avoid row-to-row shading.
See [1]_ and [2]_ for details about the equations.

Comment thread docs/sphinx/source/whatsnew/v0.16.2.rst Outdated
~~~~~~~~~~~~~
* Clarified in :py:func:`pvlib.tracking.singleaxis` that the tracker
rotation minimizes the angle of incidence (AOI) to maximize the use of
direct normal irradiance (DNI). (:issue:`2314`)

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.

Suggested change
direct normal irradiance (DNI). (:issue:`2314`)
direct normal irradiance (DNI). (:issue:`2314`) (:pull:`2869`)

~~~~~~~~~~~~~
* Clarified in :py:func:`pvlib.tracking.singleaxis` that the tracker
rotation minimizes the angle of incidence (AOI) to maximize the use of
direct normal irradiance (DNI). (:issue:`2314`) (:pull:`2869`)

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.

Suggested change
direct normal irradiance (DNI). (:issue:`2314`) (:pull:`2869`)
direct normal irradiance (DNI). (:issue:`2314`, :pull:`2869`)

@RDaxini RDaxini added this to the v0.16.2 milestone Sep 28, 2026
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.

Improve pvlib.tracking.singleaxis docstring

4 participants