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 againstsrf, e.g. viaSpectralGrid.select()).ckd_quads (
listofQuad, optional) – Quadrature rules for each bin inspectral_grid, in the same order asspectral_grid.wcenters. Required ifspectral_gridis aCKDSpectralGrid.allocation (
SampleAllocationorstr, optional) – Allocation policy. If unset (the default), the value of thesample_allocationsetting (environment variableERADIATE_SAMPLE_ALLOCATION) is used.spp_min (
int, default:2) – Minimum sample count per spectral loop iteration when the"weighted"policy splitstarget(ckd mode). Ignored in mono mode and by the"uniform"policy, which give every iterationtargetsamples. 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 ofspectral_grid(mono), or bins ofspectral_gridand, within each bin, the g-points of its quadrature rule (ckd).- Raises:
ValueError – If
targetis too low to give every iterationspp_minsamples.
Notes
With the
"weighted"policy,targetis the sample count spent on each output value of the post-processing pipeline:in mono mode, every wavelength is an output value and gets
targetsamples, whatever the SRF;in ckd mode, every bin gets
targetsamples, split across its g-points proportionally toQuad.weights;in ckd mode with a
BandSRF, the band aggregate is the output value:targetis split across bins proportionally to the SRF weight of each bin (seespectral_response_weights()), then across g-points as above. Every bin gets at leastspp_minsamples per g-point.
Counts sum exactly to
targetper output value, except that every iteration gets at leastspp_minsamples, 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
BandSRFin ckd mode, only the band aggregate (e.g.radiance_srf) getstargetsamples: per-bin results (e.g.radiance) of low-weight bins are computed from few samples and are correspondingly noisy, down tospp_minsamples per g-point in the SRF tails. Use the"uniform"policy if per-bin results matter.With the
"uniform"policy,targetapplies 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 (seeeffective_spp()).