eradiate.spectral.srf_spp_distribution#

eradiate.spectral.srf_spp_distribution(target, srf, spectral_grid, ckd_quads=None, allocation=None, spp_min=2)#

Distribute a sample count across the spectral loop iterations driven by spectral_grid.

Parameters:
  • target (int) – Sample count target.

  • srf (SpectralResponseFunction) – Spectral response function of the measure.

  • spectral_grid (SpectralGrid) – Spectral grid driving the spectral loop (already selected against srf, e.g. via SpectralGrid.select()).

  • ckd_quads (list of Quad, optional) – Quadrature rules for each bin in spectral_grid, in the same order as spectral_grid.wcenters. Required if spectral_grid is a CKDSpectralGrid.

  • allocation (SampleAllocation or str, optional) – Allocation policy. If unset (the default), the value of the sample_allocation setting (environment variable ERADIATE_SAMPLE_ALLOCATION) is used.

  • spp_min (int, default: 2) – Minimum sample count per spectral loop iteration when the "weighted" policy splits target (ckd mode). Ignored in mono mode and by the "uniform" policy, which give every iteration target samples. A value of 1 leaves the variance of single-sample iterations undefined (NaN), which makes variance outputs aggregating them (per-bin and SRF-weighted variances) NaN.

Returns:

ndarray – Sample count for each spectral loop iteration, in the order the loop visits them: wavelengths of spectral_grid (mono), or bins of spectral_grid and, within each bin, the g-points of its quadrature rule (ckd).

Raises:

ValueError – If target is too low to give every iteration spp_min samples.

Notes

With the "weighted" policy, target is the sample count spent on each output value of the post-processing pipeline:

  • in mono mode, every wavelength is an output value and gets target samples, whatever the SRF;

  • in ckd mode, every bin gets target samples, split across its g-points proportionally to Quad.weights;

  • in ckd mode with a BandSRF, the band aggregate is the output value: target is split across bins proportionally to the SRF weight of each bin (see spectral_response_weights()), then across g-points as above. Every bin gets at least spp_min samples per g-point.

Counts sum exactly to target per output value, except that every iteration gets at least spp_min samples, which makes the split only approximately proportional. Iterations with a single sample have an undefined (NaN) variance. Proportional allocation minimizes the variance of the aggregate if all iterations have the same per-sample variance; when they do not, the optimal (Neyman) allocation also weights by the per-iteration standard deviation.

With a BandSRF in ckd mode, only the band aggregate (e.g. radiance_srf) gets target samples: per-bin results (e.g. radiance) of low-weight bins are computed from few samples and are correspondingly noisy, down to spp_min samples per g-point in the SRF tails. Use the "uniform" policy if per-bin results matter.

With the "uniform" policy, target applies in full to every spectral loop iteration, g-points included (behaviour of Eradiate v1.2 and earlier).

Samplers other than "independent" may round each count up when rendering (see effective_spp()).