Conservative spectral resampling

Use this page when changing a spectral grid and deciding whether point interpolation or conservation of integrated bin content is the correct representation contract.

Representation contract¶

Contract field	Current representation
Mathematical object	A map from one explicit spectral axis to another while preserving point meaning or overlapping bin integrals according to sampling type.
Physical convention	Point samples use linear or monotone-cubic interpolation; bin averages preserve bin integrals over overlap; no extrapolation or zero filling is implied.
Runtime owner	`jaxstro.spectra` owns `SpectralPlan`, sampling enums, status values, and `resample_spectrum`.
Shape and unit policy	Source and target must share coordinate, unit, and sampling semantic; output shape is fixed by the target axis and bin edges have one more entry than bin values.
Transform boundary	Numeric axis values and edges are dynamic PyTree leaves with local fixed-interval sensitivities; coordinate kind, unit, sampling, resolving-power metadata, method, coverage policy, and shape or topology transitions are static or nonsmooth.
Evidence	Unit tests check identity paths, point methods, bin conservation, shape failures, and unsupported windows; validation reports measured spectral behavior.
Downstream interpretation boundary	Resampling does not choose instrument response, resolving-power adequacy, noise covariance, line-spread function, or acceptable scientific resolution.

Bin conservation¶

For source bin averages $\bar{f}_i$ on edges $x_i$ , conservative remapping targets the overlapping integral

\bar{g}_j = \frac{1}{y_{j+1}-y_j} \sum_i \bar{f}_i\, \left|[x_i,x_{i+1}]\cap[y_j,y_{j+1}]\right|.

(1)

Thus the sum of average times width is preserved over the shared domain. Point values do not carry the interval information needed by (1), so point-sampled spectra use an interpolation method instead.

Plans and coverage¶

SpectralPlan stores a fixed target axis, CoveragePolicy.INTERSECTION, and a point method. Source and target coordinate, unit, and sampling semantic must match. An identical axis records an identity operation in provenance. Point axes use linear or monotone-cubic interpolation; bin-average axes call the conservative remap. Nontrivial bin-integral resampling is not implemented.

If the target window extends beyond the source, the result uses NaN values and UNSUPPORTED_SPECTRAL_WINDOW. It does not extrapolate, clamp, or fill with zero.

Fixed-shape evaluation can be compiled and differentiated with respect to spectral values and same-shape numeric target coordinates. Numeric axis values and edges are dynamic PyTree leaves. The validated target-coordinate claim is local query sensitivity inside fixed intervals and away from knots. Monotone-cubic sensitivities likewise apply only inside a fixed limiter branch; knot crossings and limiter transitions are derivative boundaries.

Coordinate kind, unit, sampling semantic, resolving-power metadata, point method, and coverage policy are static metadata. A change in array shape or topology is a structural transition, not a smooth coordinate perturbation. The tests prove these local PyTree, overlap, status, and derivative contracts, not that a requested grid resolves every downstream feature.