kandersolar
commented
10 months ago Thanks @kurt-rhee. I agree that there is significant room for improvement on this topic in our documentation. We do have a bit of this kind of info in a gallery example, but it's buried and not very good anyway.
Since this info is of medium relevance to several functions, what makes the most sense to me at the moment would be to house explanation like this in a new page in the User's Guide, similar to what is being done in #1754.
In general, I think pvlib's documentation should focus on using pvlib for PV modeling (not PV modeling itself, which is probably better left to something like the PVPMC website). In this case that would mean focusing on how to represent and model trackers using pvlib. Explaining the angles and pvlib's conventions (e.g. azimuth goes clockwise from north) would fit right in, I think.
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:
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.