Singleaxis tracking with non-parallel slope (#823)

* add trackers on non-parallel slopes

- add calc_axis_tilt and calc_side_slope functions to tracking.py
- add tests for trackers on slopes
- add singleaxis tracker w/slope test data

Signed-off-by: Mark Mikofski <[email protected]>

* reverse sign for test

* update test data for sat w/slope

- match pvlib algorithms - despite disagreement

* fix stickler issues

- remove unused _get_solar_vector, oops! not part of this pr, was
 decreasing coverage

* add side_slope argument to docstring

* change max_angle to conform to convention

-  by convention this is always defined relative to the zero-point rotation not the system-plane

* stickler fixes: L459 whitespace, L456 long-line

* update test data for max_angle convention

* update to numpy-1.12.0

* use horizontal distance between rows

* use axes_dist = 1/GCR/cosd(side_slope) so axes_d
* update GCR in tests
* used more sig figs in GCR in tests so update test data
* the test data agrees with old data within 1e-5

* update api docs for trackers on side slope

* update what's new for v0.7.1 for trackers with side-slope

* use DATA_DIR from conftest

* remove os from test_tracking and old DATADIR path

* use axis tilt instead of tracker zenith

* and use axis azimuth instead of tracker azimuth

* change calc tracker axis tilt to degrees

* clarify side slope relative to horizontal

* change args/retval to degrees
* add check for relative rotation
* remove radians from test

* update side slope angle convention

* also add reference to NREL tech report
* add test with validation data set from NREL tech report

* fix stickler space complaints, see if indent helps docstring code blocks

* apply suggested comments:

* move what's new enhancements from v0.7.1 to v0.8.0
* fix returns for calc_system_tracker_side_slope()
* add Notes section to calc_tracker_axis_tilt()

Signed-off-by: Mark Mikofski <[email protected]>

* resolve conflict in what's new v0.8.0

* use implementation procedure outline in NREL tech report

* fix #824 update tests

* add units to side slope

Co-authored-by: Cliff Hansen <[email protected]>

* add see alsos

* fix docstring for calc_tracker_side_slope, rm rel_rot

* improve side-slope docstring, define rh rotation convention

* fix arg order in calc side slope

* also fix order in sat out dictionary
* test truetracking in slope-aware validation dataset

* update SingleAxisTracker class with side-slope

* add missing whitespace after comma in test_tracking.py

* catch invalid warnings for arccos in singleaxis

* update whats new v0.8.0

* with new side_slope arg in SingleAxisTracker class
* add fix for low sun angle tracker rotation calculations (issue 824)
* add links to pr 823
* ignore invalid warnings for nan > x and nan % x in tracking.py

* close #1041 prune old comments

* remove commented code, especially any code relating to use of arctan2
  adopted in 1fb82cc
* remove comments that should be sourced directly from refernces, and
  instead list reference and Eqs. numbers
* tidy up, combine lines, etc

* remove redundant "tracker" from new sat funcs

* in api.rst
* what's new v0.8.0
* tracking.py & test_tracking.py

* code review suggestions to clarify docs/comments

* side slope is line in system plane, perp. to tracker azimuth
* clarify right handed rotation of side slope in example, also replace EG with "For example"
* clarify comment defining the tracker coord-sys

Co-authored-by: Cliff Hansen <[email protected]>

* revise slope-aware tracker terms for clarity:

* use cross_axis_slope instead of side_slope
* use calc_cross_axis_tilt() instead of calc_system_side_slope()
* use slope azimuth & tilt instead of system az & ze
* clarify cross-axis tilt is measured in the tracker reference frame
* add cross-axis tilt to the SingleAxisTracker repr()
* add see also to SingleAxisTracker
* remove Lorenzo reference

* improve docstrings

* clarify cross-axis tilt by using consistent wording
* use "tracker axes" when referring to tracker axes plane (or slope)
  instead of just "slope"
* update SingleAxisTracker headline to refer user to singleaxis function
* remove redundant wording in cross_axis_tilt arg, regarding tracker axes
  plane, and make it verbatim between SingleAxisTracker, singleaxis, and
  calc_cross_axis_tilt
* improve links to module index in LocalizedSingleAxisTracker
* Improve docstring for singleaxis to be explicit about right-handed
  coordinate system of tracker reference frame and right-handed
  rotation for tracker_theta
* suggested changes to comments and do multiplication before division
* change slope_tilt to be relative to horizontal rather than defined by
  normal, also use "tracker axes plane"

* fix typos, py:class, not pv:class, in localized single-axis tracker

Co-authored-by: Cliff Hansen <[email protected]>

Author: mikofski

docs/sphinx/source/api.rst

@@ -431,6 +431,8 @@ Functions
    :toctree: generated/
 
    tracking.singleaxis
+   tracking.calc_axis_tilt
+   tracking.calc_cross_axis_tilt
 
 
 .. _iotools:

docs/sphinx/source/whatsnew/v0.8.0.rst

@@ -91,6 +91,15 @@ Enhancements
 * Added *racking_model*, *module_type*, and *temperature_model_parameters* to
   PVSystem, LocalizedPVSystem, SingleAxisTracker, and
   LocalizedSingleAxisTracker repr methods. (:issue:`1027`)
+* Added :py:func:`~pvlib.tracking.calc_axis_tilt` to calculate the
+  tracker axes tilt and :py:func:`~pvlib.tracking.calc_cross_axis_tilt` to
+  calculate the cross-axis tilt, which is the angle, relative to horizontal, of
+  the line formed by the intersection between the slope containing the tracker
+  axes and a plane perpendicular to the tracker axes. (:pull:`823`)
+* Added ``cross_axis_tilt`` argument to :py:func:`~pvlib.tracking.singleaxis`
+  and :py:func:`~pvlib.tracking.SingleAxisTracker` which defaults to zero. Use
+  :py:func:`~pvlib.tracking.calc_cross_axis_tilt` to calculate the cross-axis
+  tilt angle if necessary. (:pull:`823`)
 * Added ability for :py:func:`pvlib.soiling.hsu` to accept arbitrary time intervals. (:pull:`980`)
 * Added :py:func:`pvlib.temperature.fuentes` for cell temperature modeling. (:pull:`1037`)
 * Add :py:func:`pvlib.pvsystem.combine_loss_factors` as general purpose
@@ -102,6 +111,7 @@ Bug fixes
 * Fixed unit and default value errors in :py:func:`pvlib.soiling.hsu`. (:pull:`977`, :pull:`980`)
 * Handle NUL characters and fix version column dtype in
   :py:func:`~pvlib.iotools.crn.read_crn`. (:issue:`1025`)
+* Fix low sun angle tracker rotation calculation. (:issue:`824`)
 
 Testing
 ~~~~~~~