Add gallery example for cross-axis slope backtracking #1077

kandersolar · 2020-10-07T02:53:16Z

~~Closes #xxxx~~
I am familiar with the contributing guidelines
~~Tests added~~
~~Updates entries to docs/sphinx/source/api.rst 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 and Milestone are assigned to the Pull Request and linked Issue.
Possible to-do: remove tracking.ipynb per Singleaxis tracking with non-parallel slope #823 (comment)

As suggested in #823, here's a gallery example attempting to clarify the various angles and sign conventions in use. The static images are custom (using asymptote) for this example and can easily be modified; I am limited more by tunnel vision and lack of imagination than by the tool and welcome feedback to improve them.

rendered example: https://pvlib-python--1077.org.readthedocs.build/en/1077/auto_examples/plot_backtracking_sloped_terrain.html

cwhanse

This is quite clear, except at one point, but I have the advantage of having worked through the reference and the code already.

docs/examples/plot_backtracking_sloped_terrain.py

cwhanse · 2020-10-07T14:36:02Z

docs/examples/plot_backtracking_sloped_terrain.py

+slope_azimuth = 155  # terrain slopes down to the south-south-east
+slope_tilt = 10  # terrain is sloped at 10 degrees from horizontal


I'm confused at this point. The slope direction is 155 azimuth, but, the tilt is 10 degrees relative to what? Is it 10 degrees rotation relative to the tracker azimuth of 180? That seems an odd choice, since it is difficult to measure the slope tilt except relative to the slope azimuth.

If slope_tilt is 10 degrees relative to horizontal along slope_azimuth, then I'd suggest

Suggested change

slope_azimuth = 155 # terrain slopes down to the south-south-east

slope_tilt = 10 # terrain is sloped at 10 degrees from horizontal

slope_tilt = 10 # terrain slopes upward 10 degrees from horizontal in the direction of slope_azimuth

If slope_tilt is 10 degrees relative to horizontal along slope_azimuth,

Correct, but I think your suggested comment has the wrong sign. It's either upwards 10 degrees away from slope_azimuth, or downward 10 degrees towards it. Are you okay with this revision?

terrain slopes upward 10 degrees from horizontal away from the direction of slope_azimuth

slope_azimuth is chosen in the downslope direction? I may have missed that if it's earlier in the text. If not, would be good to add. If slope_azimuth is always downslope, then I think it may be more clear to describe slope_tilt in the direction of slope_azimuth, i.e., always negative.

Thanks for your patience with this reviewer

Changes made. As always, I am grateful for the review :)

docs/examples/plot_backtracking_sloped_terrain.py

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

…l/pvlib-python into cross_slope_example

cwhanse

LGTM and thank you @kanderso-nrel

wholmgren

Thanks @kanderso-nrel, this is very helpful. I commented on a few minor things as I read through it, but I'm ok with merging this anytime.

Would it make sense to link to the other single axis tracker example or at least put them next to each other in the menu? I don't know how that's configured.

Maybe wait to delete tracking.ipynb until we have a couple of examples for parameters like gcr and max_angle (probably in the simple single-axis tracker example).

wholmgren · 2020-10-08T16:03:46Z

docs/examples/plot_backtracking_sloped_terrain.py

+Backtracking on sloped terrain
+==============================
+
+Modeling backtracking for single-axis tracker arrays on sloped terrain.


This reads like a module docstring but renders as regular text, so I think the rendered introduction is awkward.

Agreed it's awkward in the rendered page. The reason for the strange wording is the docstring-style line is also used as the hover text for the thumbnail in the gallery listing, which has to be brief. Open to suggestions for text that works better in both contexts!

Sounds like a gallery configuration problem. Let's ignore.

wholmgren · 2020-10-08T16:09:40Z

docs/examples/plot_backtracking_sloped_terrain.py

+# sun is low in the sky. The backtracking strategy orients the modules exactly
+# on the boundary between shaded and unshaded so that the modules are oriented
+# as much towards the sun as possible while still remaining unshaded.
+# Unlike the truetracking calculation (which only depends on solar position),


Is "truetracking" (one word) widely accepted? I'd probably write true-tracking even at the cost of inconsistency with backtracking.

The existing single-axis tracker example uses the hyphenated version.

wholmgren · 2020-10-08T16:15:11Z

docs/examples/plot_backtracking_sloped_terrain.py

+        gcr=gcr,
+        cross_axis_tilt=cross_axis_tilt)
+
+    backtracking_position = tracker_data['tracker_theta'].fillna(0)


Suggested change

backtracking_position = tracker_data['tracker_theta'].fillna(0)

# tracker rotation is undefined at night

backtracking_position = tracker_data['tracker_theta'].fillna(0)

wholmgren · 2020-10-08T16:17:10Z

docs/examples/plot_backtracking_sloped_terrain.py

+# calculate the solar position
+times = pd.date_range('2019-01-01 06:00', '2019-01-01 18:00', closed='left',
+                      freq='1min', tz=tz)
+solpos = solarposition.get_solarposition(times, lat, lon)


The rendered version has some weird syntax highlighting inconsistencies. I don't see anything wrong so probably safe to ignore.

If you're talking about things being rendered blue-ish with clickable links, I think that's the intersphinx linking: https://sphinx-gallery.github.io/stable/configuration.html#add-intersphinx-links-to-your-examples

Future improvement: configure pvlib functions to link as well, or disable it for everything, for consistency.

ohhh, cool, I didn't even realize they were links. I've recently visited some of the links but not all, so it's a mix of purple and blue. Ok to ignore.

kandersolar · 2020-10-08T16:41:09Z

Would it make sense to link to the other single axis tracker example or at least put them next to each other in the menu? I don't know how that's configured.

I think related examples can be grouped into sections with folders, and besides that there is ordering functionality: https://sphinx-gallery.github.io/stable/configuration.html#sorting-gallery-subsections

Preference on introducing gallery sections here (e.g. "Weather", "PV Modeling", "Tracking") vs leaving that for another day and linking to the other example for now?

Maybe wait to delete tracking.ipynb until we have a couple of examples for parameters like gcr and max_angle (probably in the simple single-axis tracker example).

Fine by me.

cwhanse · 2020-10-08T16:44:16Z

Preference on introducing gallery sections here (e.g. "Weather", "PV Modeling", "Tracking") vs leaving that for another day and linking to the other example for now?

Was just thinking the same thing, that categories would help organize the examples.

wholmgren · 2020-10-08T18:36:39Z

I think related examples can be grouped into sections with folders, and besides that there is ordering functionality: https://sphinx-gallery.github.io/stable/configuration.html#sorting-gallery-subsections

Preference on introducing gallery sections here (e.g. "Weather", "PV Modeling", "Tracking") vs leaving that for another day and linking to the other example for now?

Thanks. Up to you. Changing this file name to plot_single_axis_tracking_on_sloped_terrain.py would also mitigate my immediate concern.

mikofski · 2020-10-09T04:11:35Z

This looks great! Thanks Kevin!

wholmgren · 2020-10-09T16:21:11Z

test failure is unrelated. thanks @kanderso-nrel!

kandersolar added 5 commits September 8, 2020 09:20

Create plot_backtracking_sloped_terrain.py

f673ac5

Merge branch 'master' into cross_slope_example

64785ad

add angle convention images

f84fb40

whatsnew

0da0d0f

Merge remote-tracking branch 'upstream/master' into cross_slope_example

6662505

cwhanse reviewed Oct 7, 2020

View reviewed changes

kandersolar and others added 5 commits October 7, 2020 20:42

Apply suggestions from code review

9d24f61

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

new images

3b75bb3

Merge branch 'cross_slope_example' of https://github.com/kanderso-nre…

fe20f01

…l/pvlib-python into cross_slope_example

reflow text for 80char limit

e1b4650

text improvements

186232c

cwhanse approved these changes Oct 8, 2020

View reviewed changes

wholmgren added the documentation label Oct 8, 2020

wholmgren added this to the 0.8.1 milestone Oct 8, 2020

wholmgren approved these changes Oct 8, 2020

View reviewed changes

kandersolar added 3 commits October 8, 2020 18:05

truetrack -> true-track

3320e19

add comment per wholmgren's suggestion

cbb8fd1

rename file

5dd6d46

wholmgren merged commit c24bab0 into pvlib:master Oct 9, 2020

kandersolar deleted the cross_slope_example branch October 9, 2020 16:22

kandersolar mentioned this pull request Aug 7, 2021

How to organize the example gallery? #1271

Closed

kandersolar mentioned this pull request Jul 6, 2022

Move surface orientation calculation from tracking.singleaxis to new function; switch to Marion & Dobos 2013 equations #1480

Merged

8 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add gallery example for cross-axis slope backtracking #1077

Add gallery example for cross-axis slope backtracking #1077

kandersolar commented Oct 7, 2020 •

edited by wholmgren

Loading

cwhanse left a comment

cwhanse Oct 7, 2020

kandersolar Oct 8, 2020

cwhanse Oct 8, 2020

cwhanse Oct 8, 2020

kandersolar Oct 8, 2020

cwhanse left a comment

wholmgren left a comment

wholmgren Oct 8, 2020

kandersolar Oct 8, 2020

wholmgren Oct 8, 2020

wholmgren Oct 8, 2020

wholmgren Oct 8, 2020

wholmgren Oct 8, 2020

wholmgren Oct 8, 2020

kandersolar Oct 8, 2020

wholmgren Oct 8, 2020

kandersolar commented Oct 8, 2020

cwhanse commented Oct 8, 2020

wholmgren commented Oct 8, 2020

mikofski commented Oct 9, 2020

wholmgren commented Oct 9, 2020

		slope_azimuth = 155 # terrain slopes down to the south-south-east
		slope_tilt = 10 # terrain is sloped at 10 degrees from horizontal

	slope_azimuth = 155 # terrain slopes down to the south-south-east
	slope_tilt = 10 # terrain is sloped at 10 degrees from horizontal
	slope_tilt = 10 # terrain slopes upward 10 degrees from horizontal in the direction of slope_azimuth

	backtracking_position = tracker_data['tracker_theta'].fillna(0)
	# tracker rotation is undefined at night
	backtracking_position = tracker_data['tracker_theta'].fillna(0)

Add gallery example for cross-axis slope backtracking #1077

Add gallery example for cross-axis slope backtracking #1077

Conversation

kandersolar commented Oct 7, 2020 • edited by wholmgren Loading

cwhanse left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cwhanse left a comment

Choose a reason for hiding this comment

wholmgren left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kandersolar commented Oct 8, 2020

cwhanse commented Oct 8, 2020

wholmgren commented Oct 8, 2020

mikofski commented Oct 9, 2020

wholmgren commented Oct 9, 2020

kandersolar commented Oct 7, 2020 •

edited by wholmgren

Loading