Description
Is your feature request related to a problem? Please describe.
During the pvlib user session at PVPMC Europe, someone asked for more explanation regarding the different angles that are used in pvlib. I would like to provide some of my understanding, if it would help to make pvlib's documentation more understandable. Especially for those who are newer to the field.
I took a look at the current documentation for calc_surface_orientation: https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.tracking.calc_surface_orientation.html which gives a link to the Marion paper in the references. The marion paper gives a diagram to explain the differences between the types of angles used to describe the module orientation, but in my opinion the diagram is a bit hard to read. A copy of the diagram is included below.
Describe the solution you'd like
I am not sure whether a disambiguation like the one that is written at the bottom of this post should live inside of the documentation of the function itself, or if it should live in a separate disambiguation page like the docs or even the pvpmc website. I will leave it up to the maintainers what is done with the information below, whether that be inclusion somewhere in the documentation set or nothing at all.
Describe alternatives you've considered
The documentation also be left as is, or updated in a different way.
Additional context
Hello pvlib matintainers. Here are some notes explaining a topic that a new user may find confusing about the different types of angles that exist in pvlib. Hopefully the language used is plain and simple enough for
The main source of confusion in my opinion is that there are two different sets of angles that one could theoretically use to describe the same system.
The first set of angles, generally correspond to the pitch, yaw and roll angles that one might ascribe to the orientation of an airplane. This is the set of angles that most people use to describe tracker systems. In this analogy:
- "pitch" is analogous to "torque tube axis tilt". Another way to describe this by asking if there is elevation change from one end of the tracker to the other end. If so, then the pitch can be measured via geometric operations and is non-zero.
- "yaw" is analogous to "azimuth"
- "roll" is analogous to "tracker rotation angle about the torque tube"
Another way to describe the orientation of the modules, rather than describing their relationship with the torque tube is to instead describe the normal vector that points outward from the module surface. This normal vector can be described in spherical coordinates of unit length. This way of describing the module's orientation is roughly analogous to how people describe the orientation of fixed tilt systems. In pvlib, this type of description is called "surface angles".
As a user of pvlib, I find that having one set of angles to work with (aka the surface angles) makes the code base very flexible. Since most (or all?) of the geometry related function in pvlib take surface angles, I just need to call calc_surface_orientation one time for tracker systems, and then the rest of my program works without any edits whether my system is tracker or fixed tilt.
I hope this write-up is useful for anybody who is confused about the difference between tracker angles and surface angles, and I hope that it serves as a good starting point for expanding the documentation in the pvlib library.