Default MAX_X_GROUND is too small for simulations with many rows

[kandersolar]

By adjusting the gcr, pvrow_width, and n_pvrows inputs it is possible to simulate arrays covering an arbitrarily large distance. For typical inputs (e.g. n_pvrows=3, pvrow_width=4, gcr=0.4), the spanned distance is relatively small, but it's not wholly unreasonable to model a system with, for example, n_pvrows=15, gcr=0.5, pvrow_width=6, in which case the simulated array spans over 100 meters between the first and last rows. The reason this matters is because the default value of MAX_X_GROUND is 100, so the farthest segments in the scene get ignored entirely in the above extreme example. This leads to strange effects like the following, where legend entries indicate pvrow_height and pvrow_width:

Because the row width to height ratio is constant across all three variants, I'd expect the returned irradiance values to be identical. However, they are not, and it's due to an increasingly large portion of the array crossing that MAX_X_GROUND boundary as the array scale increases. By setting MAX_X_GROUND to a number large enough to capture the entire array, the difference disappears and the three curves overlap as expected. Here is some code to reproduce:

Click to expand!

from pvfactors import config
# uncomment these lines to make the three lines overlap
#config.MAX_X_GROUND = 1e3
#config.MIN_X_GROUND = -config.MAX_X_GROUND

import pvfactors
from pvfactors import geometry
import pvlib
import pandas as pd
import matplotlib.pyplot as plt

times = pd.date_range('2019-12-21 11:30', '2019-12-21 13:05', freq='5T', tz='Etc/GMT+5')
loc = pvlib.location.Location(40, -80)
sp = loc.get_solarposition(times)
cs = loc.get_clearsky(times)
tr = pvlib.tracking.singleaxis(sp.zenith, sp.azimuth, gcr=0.5)

data = {}
for height, width in [(1.5, 2.0), (3.0, 4.0), (4.5, 6.0)]:
    ret = pvlib.bifacial.pvfactors_timeseries(sp.azimuth, sp.zenith,
                                              tr.surface_azimuth, tr.surface_tilt,
                                              180, times, cs.dni, cs.dhi,
                                              0.5, height, width, 0.2,
                                              n_pvrows=15, index_observed_pvrow=7)
    data[f'({height}, {width})'] = ret[1]
pd.DataFrame(data).plot(figsize=(7, 4))
plt.ylabel('Rear-Side Irradiance [W/m2]')

For reference, the above plot was generated with pvfactors 1.5.1 and pvlib 0.8.1.

---

The above scenario is certainly unusual, but I don't think it's out of the realm of reasonable usage. Here are some ideas:

• Increase the MAX_X_GROUND and MIN_X_GROUND values. I'm not sure what consequences this would have, if any, for more typical simulations.
• Emit a warning if the simulated array is large enough for the default values to be problematic, for example if any of the rows extends beyond the limit, or maybe any of the ground shadows or something.
• Mention in the documentation somewhere how to increase these limits on the user's end like I've done in the above example. I think pvfactors.config is not mentioned anywhere in the sphinx docs, though maybe I've just missed it.

cc @spaneja

[anomam]

Thanks for this @kanderso-nrel 🙌 you're hitting all those cases that - at the time I wrote the code - were "edge" cases for SunPower; I'm sorry I didn't plan for better solutions back then, but at the same time I'm happy the code has lived long enough that someone cared to test these situations : )

Right now MAX_X_GROUND and MIN_X_GROUND are indeed constants (also undocumented, sorry...), but they don't have to be. We could let the users choose their values, but ideally I think it would be nice if pvfactors could also increase (and decrease?) the values automatically as the the size of the array changes. But I think a study would be needed though to understand 1) when to increase the values and 2) by how much (the minimum values)...

[kandersolar]

To clarify: I don't mean at all for these issues to sound like complaints! It's very cool that pvfactors is flexible enough to push these boundaries. And I think it's telling that I had to go all the way to pvrow_height=4.5 and n_pvrows=15 to start getting strange results ;) I think it's also telling that I was able to figure out what the problem was and work around it, despite being largely unfamiliar with the internals of pvfactors. So kudos for writing good code :)

Agreed that automatically setting the min/max boundaries based on array size would be nice. I'll think a bit on this, but no promises I'll be able to open a PR any time soon...