pvlib: one site turned every output into NaN

EN | 한국어

One coordinate pair produced eight NaN values: no usable numerical output. Adding a second copy of that exact coordinate restored the input signal. I reproduced this boundary case in pvlib’s Wavelet Variability Model (WVM), then checked what the underlying equation requires when there is only one site.

WVM estimates how combining sunlight signals from several locations smooths their fluctuations. A cloud shadow may reach one location before another, so their rises and falls need not coincide. With just one location, there is no spatial aggregation to perform; the published equation reduces to preserving the original signal.

Eight synthetic numbers, not a solar-plant measurement

The input alternates between 1 and 0.2. These are clear-sky index values: sunlight relative to an estimate for clear conditions. I used a synthetic sequence, not observed clouds or plant data, with coordinates in metres, cloud speed 10 m/s, and samples 60 seconds apart.

x = [1, .2, 1, .2, 1, .2, 1, .2]
positions = [[0, 0]]   # one site, coordinates in m
cloud_speed = 10       # m/s
dt = 60                # seconds
# One site: eight NaNs
# Two identical coordinates: unchanged x

The result reproduces in pvlib 0.16.1 and the pinned main code from October 2026; their scaling.py files are byte-identical. The public function description does not appear to require at least two sites. Rather than treating the NaNs as an unexplained special case, I returned to the model’s correlation sum.

Counting sites backwards from their distances

Lave and colleagues’ 2013 equation defines the variability-reduction factor VR as the square of the site count N divided by the sum of all correlations. A correlation describes how closely two locations vary together. A site’s correlation with itself is 1, so one site gives VR = 1² / 1 = 1 at every timescale. WVM splits the signal into components at different timescales and divides them by √VR; a factor of 1 leaves those components unchanged.

VR = N**2 / sum_m sum_n rho(d_mn, timescale)
# One site: one self-correlation → VR = 1

n_pairs = N * (N - 1) / 2
# Zero distance pairs fits both N=0 and N=1

The implementation estimates N from the number of pairwise distances instead of counting the supplied coordinates. One site has zero distance pairs, but zero sites also satisfy that equation. The numerical search starts at zero and returns N=0, leading to 0/0. It is like declaring an attendee list empty because nobody shook hands: the handshake count cannot distinguish one person from none. Here the analogy is limited to counting pairs.

The coordinates already exist inside the function, so the candidate change is n_dist = pos.shape[0]: use the number of coordinate rows directly. Rejecting an actually empty layout is a separate input-validation question.

What the 27 checks establish

In an AI-assisted local audit, I checked the original code and the candidate using the 16 existing test_scaling.py tests plus 11 added regression cases. Regression tests check that previously working cases still work after a change. These include single-site arrays and Series inputs—sequences with labels such as timestamps—at 0.5, 1, 60, and 300-second intervals, plus coincident-site checks. The original code gives 9 failures and 18 passes; the candidate passes all 27 selected tests. This is not a full pvlib-suite result.

A separate full-matrix correlation sum agrees within 1.8 × 10⁻¹⁵ for deterministic layouts of 1, 2, 3, 4, 10, and 100 sites. The candidate exactly preserves the original VR values for the tested multi-site layouts. These checks address the limiting case and targeted regressions, not performance on real-plant data. I also found the count-inference pattern in Sandia’s original MATLAB source, but did not execute MATLAB.

As checked on 13 October 2026, issue #2895 remains open with zero comments. The candidate is not merged. The report provides a reproducible explanation and a bounded change for review, rather than an adopted library correction.

Sources and reproduction: pvlib issue #2895 · Original WVM paper