[Feature Preview] Shadow casting on and by flat surfaces

[echedey-ls]

• Closes Direct and diffuse shading factors - spatial approach (for Photosynthetically Active Radiation) #2069
• I am familiar with the contributing guidelines
• 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.

Briefing

Objectives

• Provide an API to calculate shades
• Intuitive
• Trying to follow the references

Possibly there's only one I have achieved.
⚠️ Trigger warning for reviewers: crap unfinished code

General modifications this PR introduces

• pvlib.spatial module with two classes:
  • FlatSurface, can shade and can be shaded
  • RectangularSurface, inherits from above but allows for easy building of the common instance
• Two examples
  • Calculation of shades geometries + easy plot of row to row for a unique instant
    • Sandbox for myself, and for other people to play, test it
  • First example (fixed tilt) of the paper [1] in Direct and diffuse shading factors - spatial approach (for Photosynthetically Active Radiation) #2069 , Figure 9, top plot
    • Animation of the simulation
• New config option of sphinx-gallery to allow animations
• New dependency, shapely (probably should be pinned to >= 2)

What is pending

• Completing the test suite
• Polishing docs
• Implement the generic FlatSurface.plot() method
• Implement FlatSurface.combine_2D_shades() to avoid overlapping shades (make it the default in .get_2D_shades_from()

Long-term roadmap

• Add 3D objects (the same projection of points, but using a ConvexHull to calculate the shade boundaries for certain objects or maybe composing of flat surfaces)
• Add opacity and the inclusion-exclusion algorithm to calculate the resulting shade transparency
• Add conical objects, i.e. trees

Where & why I did not follow the references in some cases:

• Angle convention used has been the one described by the familiar reference Slope-Aware Backtracking for Single-Axis Trackers - NREL
• Added rotation of surfaces, the known axis_tilt
• Added a surface point to the calculation of the interceptions. The original reference describes projecting the shadows onto the plane that goes through the origin, but I thought that is super-antiintuitive for any kind of user since it would make the coordinate system fixed to each item being shaded. In other words, a shading scene per shaded object. The extra step is a translation (points difference) of the projected object.

Other information about the solution

• Does not use rotation matrices (originally it did): it uses the scipy spatial Rotation object, faster (quaternions), implements broadcasting, handy ways of instantiating the object
• Relies on shapely Polygons for a lot of things

Controversial features (like if there weren't already enough)

• Does not allow the input to be a timeseries, only an instant (scalar solar zenith and azimuth)

Status and discussion

You see, this is unfinished. I wouldn't allow myself to do this to you, but in one of the GSoC meetings I was hinted (fairly) that maybe this does not fit this repo. That maybe it does creating another repo under the pvlib organization. Maybe not even that.

And since there wasn't much conversation at #2069, opening this PR is partly to kickstart the discussion regarding that.

Regarding the model, the simulated plot:

Does not match the results for the Winter Solstice:

Docs

• Spatial module
  • FlatSurface: https://pvlib-python--2106.org.readthedocs.build/en/2106/reference/generated/pvlib.spatial.FlatSurface.html
  • RectangularSurface: https://pvlib-python--2106.org.readthedocs.build/en/2106/reference/generated/pvlib.spatial.RectangularSurface.html
• Examples
  • Minimal example for instantaneous data: https://pvlib-python--2106.org.readthedocs.build/en/2106/gallery/shading/plot_spatial_row_to_row_shading.html#sphx-glr-gallery-shading-plot-spatial-row-to-row-shading-py
  • PAR shading example, animation: https://pvlib-python--2106.org.readthedocs.build/en/2106/gallery/agrivoltaics/plot_par_direct_shading0_fixed_tilt.html#sphx-glr-gallery-agrivoltaics-plot-par-direct-shading0-fixed-tilt-py

[echedey-ls]

Ready for preview @kandersolar , @AdamRJensen , @cwhanse , the rest of @pvlib/maintainers (I can't ping the team)

Feel free to weight in whatever comes to your mind, but firstly focus on whether pvlib is a good place for this please. TIA.

[echedey-ls]

@mikofski , @adriesse , @markcampanelli would you like to weight in whether pvlib is a good place to include this? So I can determine if I should continue working on the code or not.

Docs

• Spatial module
  - FlatSurface: https://pvlib-python--2106.org.readthedocs.build/en/2106/reference/generated/pvlib.spatial.FlatSurface.html
  - RectangularSurface: https://pvlib-python--2106.org.readthedocs.build/en/2106/reference/generated/pvlib.spatial.RectangularSurface.html
• Examples
  - Minimal example for instantaneous data: https://pvlib-python--2106.org.readthedocs.build/en/2106/gallery/shading/plot_spatial_row_to_row_shading.html#sphx-glr-gallery-shading-plot-spatial-row-to-row-shading-py
  - PAR shading example, animation: https://pvlib-python--2106.org.readthedocs.build/en/2106/gallery/agrivoltaics/plot_par_direct_shading0_fixed_tilt.html#sphx-glr-gallery-agrivoltaics-plot-par-direct-shading0-fixed-tilt-py

[adriesse]

@mikofski , @adriesse , @markcampanelli would you like to weight in whether pvlib is a good place to include this? So I can determine if I should continue working on the code or not.

My initial reaction is that it is probably a good basic functionality for the pvlib toolbox. I haven't looked under the hood, but maybe the PR can be split up a bit. Also details of OO interface could perhaps be debated.

[cwhanse]

I am not in favor of building 3D lighting/shade calculators into pvlib-python. My reasons:

• I think the code base will necessarily be large and I worry about long-term maintenance
• it is likely to introduce dependencies that aren't used elsewhere in pvlib (e.g. shapely)
• I can't help but think that lighting/shade calculations are already being done in other libraries and pvlib would only need some shim code. Perhaps that's wishful thinking.

For these reasons, I think a new project (pvlib3d?) makes more sense than pvlib.spatial.

[echedey-ls]

Seems like there is consensus on not including something like this here, so I'm closing this PR.