Function calibrate_energy 

pub fn calibrate_energy(
    energies_nominal: &[f64],
    transmission: &[f64],
    uncertainty: &[f64],
    isotopes: &[ResonanceData],
    abundances: &[f64],
    assumed_flight_path_m: f64,
    temperature_k: f64,
    resolution: Option<&InstrumentParams>,
) -> Result<CalibrationResult, PipelineError>

Calibrate the energy axis of a TOF neutron measurement.

Given a measured 1D transmission spectrum and known sample composition (e.g. natural Hf), finds the (L, t₀) that minimize chi² by aligning the ENDF resonance positions with the measured dips.

Search strategy

The optimisation runs as three nested coarse → fine → ultra-fine grid scans on (L, t₀). At each (L, t₀) candidate, the third parameter n_total (total areal density, atoms/barn) is optimised by golden-section search in log10(n) space over the documented user-supported interval [1e-5, 1e-2] atoms/barn. Searching in log space gives uniform relative resolution across the three-decade band, which is necessary because realistic samples span from ~1e-5 (trace) to ~1e-2 (1 mm metal foils).

Internally the golden section runs on a slightly wider band (~5e-6 to ~2e-2) so the boundary-saturation guard’s ~5 % linear tolerance does not exclude a true optimum at the documented edges; if the optimum lands inside the tolerance window — i.e. effectively at 1e-5 or 1e-2 — the function returns Err(PipelineError::InvalidParameter) rather than a silent boundary-saturated answer, because a true minimum at the edge almost always means the real optimum lies outside the supported interval and the caller should supply a better initial estimate or check the sample composition.

Arguments

• energies_nominal — Energy grid computed with assumed L (ascending, eV)
• transmission — Measured transmission values (same length)
• uncertainty — Per-bin uncertainty (same length)
• isotopes — ENDF resonance data for each isotope
• abundances — Natural abundance fractions (same length as isotopes, sum ≤ 1)
• assumed_flight_path_m — The L used to compute energies_nominal
• temperature_k — Sample temperature for Doppler broadening
• resolution — Optional instrument resolution function. When provided, the forward model includes Doppler + resolution broadening, producing more accurate (L, t₀) fits. Without resolution, fitted parameters absorb the missing broadening and may be biased.

Returns

CalibrationResult with the fitted (L, t₀, n_total) and corrected energies.