pub fn calibrate_resolution(
family: ResolutionFamily,
energies: &[f64],
data: &[f64],
unc: &[f64],
sample: &SampleParams,
config: &CalibrationConfig,
) -> Result<CalibrationResult, FittingError>Expand description
Calibrate the resolution parameters of family against a known-(ρ,T)
calibrant.
sample carries the FIXED density and temperature (and isotopes/groups). By
default only the resolution shape/width is optimized, at the pinned energy
scale (t0, L_scale) = (center, center) — a pure broadening calibration on an
already energy-calibrated grid (this is the SAMMY split: resolution is a
broadening kernel; t0/L are a separate energy-scale calibration).
Set CalibrationConfig::fit_t0/fit_l_scale
(e.g. via CalibrationConfig::with_position_prior) to also fit the SHARED
energy-scale (t0, L_scale) under a Gaussian metrology prior — for joint
energy-scale work or a cross-family identifiability study. Do not fit
position with a flat prior in production: the asymmetric-kernel mode→centroid
lag is the same 1/√E basis as L_scale, so a free L_scale absorbs the lag
and corrupts the calibrated width.
The IC family fits the full bounded moderator shape (#642): α(E) = e^{θ0}√E + e^{θ1} — positive at every energy by construction — plus free
bounded β = e^{θ2} and scalar storage fraction R = θ3 ∈ [0, 1], folded
with the SNS PSR channel triangle
(CalibrationConfig::psr_fwhm_ns, default 350 ns; 0 disables;
optionally fitted via IkedaCarpenter { fit_psr: true } — a zero width
combined with fit_psr contradicts “0 disables” and is rejected).
Returns the fitted shape parameters, the reduced data χ²/dof, the fitted (or
pinned) (t0, L_scale), the prior penalty, the calibrated
ResolutionFunction (ready to pin), the free-parameter count
(CalibrationResult::n_free_params), and the pinned-bound report
(CalibrationResult::bounds_hit).
§Errors
FittingError::EmptyData / FittingError::LengthMismatch for bad
inputs; FittingError::InvalidConfig for a bad grid or position config;
propagates optimizer errors.