[us-commits] [ehb54/ultrascan3] f9bdfd: somo/doc: theory page for GRPY shell reduction, wi...

[emre brookes]

  Branch: refs/heads/ehb54-issue-984
  Home:   https://github.com/ehb54/ultrascan3
  Commit: f9bdfd141549a30df1cab9c799cc167486a11659
      https://github.com/ehb54/ultrascan3/commit/f9bdfd141549a30df1cab9c799cc167486a11659
  Author: ehb54 <brookes at 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 at anthropic.com>



To unsubscribe from these emails, change your notification settings at https://github.com/ehb54/ultrascan3/settings/notifications