Struct ResolutionPlan 

pub struct ResolutionPlan { /* private fields */ }

Pre-built resolution-broadening plan for a specific target energy grid.

Encodes every quantity that depends only on the target grid, the reference kernel, and the flight path — so applying the plan to a spectrum reduces to a gather + multiply-add loop with no transcendentals, no allocations, and no binary / pointer search.

Build via TabulatedResolution::plan — returns a Result and validates the sorted-grid precondition that broaden enforces. Apply via ResolutionPlan::apply. One plan is tied to one (target_energies, ref_energies, flight_path_m) triple; the plan owns a copy of the target-energy grid so callers cannot apply it to a spectrum that was measured on a different grid even when the grid length matches — use Self::target_energies to verify the grid identity before applying.

The layout is a flat Struct-of-Arrays (SoA): per-target (lo_idx, frac, weight) tuples packed into three parallel Vecs, with starts[i]..starts[i+1] naming the range for target i. SoA keeps the inner loop memory-access pattern sequential and cache-friendly.

Implementations

impl ResolutionPlan

pub fn len(&self) -> usize

Number of target energies this plan covers.

pub fn is_empty(&self) -> bool

True when the plan covers no target energies.

pub fn target_energies(&self) -> &[f64]

Target energy grid the plan was built for.

Callers implementing plan caches can compare this against their current grid to decide whether the plan is still valid. Using pointer identity of the returned slice gives an O(1) check when the grid hasn’t moved; slice equality is O(n) but catches cases where the underlying buffer was reallocated.

pub fn apply(&self, spectrum: &[f64]) -> Vec<f64>

Apply the plan to a spectrum on the same target grid the plan was built for.

The spectrum length must equal Self::len. Passing a spectrum on a different grid that happens to have the same length is caller error — verify via Self::target_energies when in doubt.

Bit-exact with broaden_presorted(target_energies, spectrum) for finite spectrum values; degenerate-bracket entries short-circuit the interpolation so the equivalence also holds when spectrum[lo+1] is NaN or ±∞ (the reference path returns spectrum[lo] directly in that case without touching the upper bracket).

pub fn compile_to_matrix(&self) -> ResolutionMatrix

Compile this plan into a row-stochastic CSR ResolutionMatrix.

The compiled matrix is an explicit sparse representation of the resolution operator R on the plan’s target grid. Each row sums to 1.0 to machine precision (passthrough rows store a single (i, i, 1.0) entry to match ResolutionPlan::apply ’s norm ≤ DIVISION_FLOOR fallback).

Degenerate-bracket handling uses the -0.0 sentinel convention introduced in PR #470: if plan.frac[e] has the bit pattern of -0.0, the entry contributes weight / norm at column lo only (no lo+1 bracket). A regular +0.0 frac contributes weight * 1.0 / norm at lo and weight * 0.0 / norm = 0.0 at lo+1 — those zero columns are retained in CSR with value = 0.0 to preserve downstream NaN-safety if the consumer re-multiplies by a spectrum containing NaN at lo+1.

Equivalence contract (finite spectra only)

For a spectrum with all finite values, apply_r on the compiled matrix produces per-element output within 1e-12 relative tolerance of Self::apply on the same spectrum — not bit-exact, because the CSR matvec sums contributions in column order while apply sums in entry order and IEEE-754 addition is non-associative. The 1e-12 bound accounts for accumulation error across the ~82 entries per row on the 3471-bin VENUS production grid (500 × 2.22e-16 ≈ 1.1e-13 per row; 1e-12 leaves comfortable headroom).

Non-finite and near-overflow spectra

The equivalence bound does NOT extend to spectra with NaN / ±∞ values, nor to near-f64::MAX overflow inputs (Codex round-2 P3). Both divergences trace back to the same algebraic rewrite:

• Self::apply computes each entry as spec[lo] + frac * (spec[lo+1] - spec[lo]), which can overflow the subtraction even for finite inputs (opposite-sign f64::MAX → -∞).
• The compiled CSR form splits the interp into (1 - frac) * spec[lo] + frac * spec[lo + 1], which scales before summing and stays finite in the same case.

For bounded finite Beer-Lambert transmissions (T ∈ [0, 1]) neither divergence can arise; callers who deliberately pass non-finite or near-overflow spectra (e.g., as debug sentinels or out-of-range diagnostics) must not rely on cross-API equivalence. See resolution_matrix_nonfinite_contract and resolution_matrix_large_finite_contract for executable demonstrations.

Trait Implementations

impl Clone for ResolutionPlan

fn clone(&self) -> ResolutionPlan

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ResolutionPlan

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.