Branch: refs/heads/ehb54-issue-984 Home: https://github.com/ehb54/ultrascan3 Commit: f9bdfd141549a30df1cab9c799cc167486a11659 https://github.com/ehb54/ultrascan3/commit/f9bdfd141549a30df1cab9c799cc16748... Author: ehb54 <brookes@uthscsa.edu> Date: 2026-08-07 (Fri, 07 Aug 2026) Changed paths: M us_somo/somo/doc/manual/somo/somo_hydro.html A us_somo/somo/doc/manual/somo/somo_hydro_shell_reduction.html Log Message: ----------- somo/doc: theory page for GRPY shell reduction, with the mathematics and references The user-facing documentation named Richardson extrapolation in a single sentence and stopped there. The mathematics existed only in the module README and the header comments, neither of which a SOMO user reads. New page somo_hydro_shell_reduction.html, following the existing theory-page pattern (cormap.html, IntegralBaselineTheory.html), linked from the sentence that previously stood alone. It covers why bead count dominates the cost, how the subsets are chosen and why by fraction rather than by exposure threshold, the extrapolation itself, the safeguards, per-quantity convergence, the extent of the testing, and what the option is and is not for. Every formula and constant on the page was checked against the implementation rather than written from memory: the order equation, the remaining-error and extrapolated-value expressions, the clamp range, the 1.5 safety factor, the half-the-raw-gap floor, the default ladder, and the 8/7 geometric cost. Two things it makes explicit that the documentation did not say anywhere: - The extrapolation needs THREE subsets. A run that stops after two -- because it converged at once, or because memory allowed no more -- reports the raw inter-rung difference instead. Still conservative, but cruder, and decided by how the ladder happens to stop rather than by anything the user set. - "Shell reduction" is NOT the classical shell model. That method replaces the particle with surface beads and extrapolates to zero bead radius; this one retains existing beads and extrapolates to the complete model. Same physical motivation, both extrapolations to a limit, different procedures -- and an easy confusion for exactly this audience. References: Richardson 1911 and Richardson & Gaunt 1927 for the method; Roache 1994/1998 for the three-level observed-order practice this follows (the Grid Convergence Index, with bead count in place of grid spacing); Shrake & Rupley 1973 for the exposure calculation; Garcia de la Torre & Bloomfield 1981 and Carrasco & Garcia de la Torre 1999 for the shell-model context distinguished above; Zuk et al 2018 and Brookes & Rocco 2018 for GRPY and SOMO. Fixes ehb54/ultrascan-tickets#984 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> To unsubscribe from these emails, change your notification settings at https://github.com/ehb54/ultrascan3/settings/notifications