Module resolution

Expand description

Resolution broadening via convolution with instrument resolution function.

Convolves theoretical cross-sections (or transmission) with the instrument resolution function to account for finite energy resolution. The resolution function is modeled as a Gaussian with energy-dependent width, optionally combined with an exponential tail, derived from time-of-flight instrument parameters.

§SAMMY Reference

rsl/mrsl1.f90 — Main RSL resolution broadening routines (Resbrd)
rsl/mrsl4.f90 — Resolution width calculation (Wdsint, Rolowg)
rsl/mrsl5.f90 — Exponential tail peak shift (Shftge)
fnc/exerfc.f90 — Scaled complementary error function
convolution/DopplerAndResolutionBroadener.cpp — Xcoef quadrature weights
Manual Section III.C (Resolution Broadening); quadrature Eq. IV B 3.8 (R3-revision numbering — see compute_xcoef_weights and the Gaussian+exponential path in resolution_broaden_presorted)

§Width convention — read before supplying a number

Every width here is a W-parameter, the width appearing in exp(-x²/W²), not a standard deviation. The two differ by √2:

σ = W/√2 FWHM = 2·√(ln 2)·W = 1.6651·W

This is SAMMY’s convention, and it is the same one the Doppler width Δ_D uses, so the two broadening kernels compose without a conversion. Supplying a 1σ value where a W is expected yields a kernel √2 too narrow — 29 % — and a resolution that is too narrow is absorbed into a fitted temperature that is too high.

ResolutionParams::from_sigma and ResolutionParams::from_fwhm convert for you. Use them rather than scaling by hand.

SAMMY’s own inputs are in yet other measures — Deltag is a FWHM and Deltal is the full width of a rectangular path spread — so reading a SAMMY .inp goes through nereids_endf::sammy::sammy_to_nereids_resolution (Deltag/(2√ln2), Deltal/√6), never straight into these fields.

§Physics

For a time-of-flight instrument, the energy resolution is:

(ΔE/E)² = (2·Δt/t)² + (2·ΔL/L)²

where t = L/v is the neutron time-of-flight, Δt is the total timing width, and ΔL is the flight path width — both W-parameters, as above, so ΔE is one too. The factor 2 is the kinematic derivative dE/E = 2·dt/t; it is not a width-measure conversion. Since t ∝ 1/√E, the timing contribution gives ΔE ∝ E^(3/2) while the path contribution gives ΔE ∝ E.

The broadened cross-section is:

σ_res(E) = ∫ R(E, E’) · σ(E’) dE’

When Deltae = 0, R is a pure Gaussian (Iesopr=1): R(E, E’) = exp(-(E-E’)²/Wg²) / (Wg·√π)

When Deltae > 0, R is the convolution of a Gaussian with an exponential tail (Iesopr=3): R(E, E’) ∝ exp(2·C·A + C²) · erfc(C + A)

where C = Wg/(2·We), A = (E - E’)/Wg, Wg = Gaussian width, We = exponential width. This is the analytical result for convolving exp(-x²/Wg²) with exp(-x/We)·H(x).

Structs§

ResolutionMatrix: Row-stochastic CSR representation of the resolution operator R on a fixed target energy grid.
ResolutionParams: Resolution function parameters for time-of-flight instruments.
ResolutionPlan: Pre-built resolution-broadening plan for a specific target energy grid.
TabulatedResolution: A tabulated resolution function from Monte Carlo instrument simulation.

Enums§

ResolutionError: Errors from resolution broadening operations.
ResolutionFunction: Resolution function: analytical Gaussian, tabulated from Monte Carlo, or analytical Ikeda–Carpenter moderator model.
ResolutionParamsError: Errors from ResolutionParams construction.
ResolutionParseError: Errors from resolution file parsing.

Constants§

TOF_FACTOR: TOF conversion factor: t (μs) = TOF_FACTOR × L (m) / √(E in eV).

Functions§

apply_r: Apply a compiled ResolutionMatrix to a spectrum on the same target grid the matrix was compiled for.
apply_resolution: Apply resolution broadening using either Gaussian or tabulated kernel.
apply_resolution_with_matrix: Checked variant of apply_r that validates the matrix was compiled for energies before applying.
apply_resolution_with_plan: Apply resolution broadening, optionally via a pre-built ResolutionPlan.
build_resolution_plan: Build a broadening plan for (energies, resolution).
resolution_broaden: Apply Gaussian resolution broadening to cross-section data.